Self Attribution
Overview
For self-attribution integration with Liftoff, there are three steps that your servers must handle:
- Receive incoming users from Liftoff, store their device ID and tracking token, and redirect them to your App Store page.
- Perform attribution for installs and events to determine if Liftoff drove those users.
- For events that are attributed to Liftoff, send user and event info to Liftoff's postback URL.
When a user clicks on an ad, we redirect them to your server using your Click URL and pass you their device ID (IDFA for iOS, Google AID for Android), and a unique Liftoff tracking token. These values are used later to attribute installs and events, so they must be stored on your server. You then redirect the user to your App Store page, where they can download your app.
After a user has downloaded the app, and each time they complete an event in your app that you would like us to track, you check if that user is attributed to Liftoff by comparing their device ID with the device IDs from the Click URLs we sent you. If they are a Liftoff-attributed user, you then fill out our postback template with the event information, and send that back to us, so we can track these events and optimize our future spend for you.
Receive incoming users from Liftoff
Each time a user clicks on an ad, we take the Click URL template you provide us, fill in the requested parameters, and redirect the user to that URL. Some of these parameters must be stored and passed back to Liftoff with each postback; others are optional and are purely for your analysis.
| {TRACKING_TOKEN} | Required. A unique token that we use to match each click event to the postback events you will send us. This must be passed back to us as a parameter on the install postback and any post-install event postbacks for the user originating from this click. |
|---|---|
| {IDFA} | Required for iOS. Apple's identifier for advertising. |
| {GOOGLE_AID} | Required for Android. |
| {CREATIVE_NAME} | The name of the ad which led to this click. |
| {CREATIVE_SIZE} | The dimensions of the ad which led to this click. |
| {EXTERNAL_ID} | The app-specific Liftoff App ID for the current app (see below for more information). |
| {CAMPAIGN_NAME} | Campaign name. |
| {CAMPAIGN_EXTERNAL_ID} | Unique ID for campaign. |
| {COUNTRY_THREE_LETTER} | ISO ALPHA-3 country code (e.g. "USA"). |
| {COUNTRY_TWO_LETTER} | ISO ALPHA-2 country code (e.g. "US"). |
| {UNIX_TIME} | Click time. |
| {DEVICE_IP} | IP address of requesting device. |
| {DEVICE_FAMILY} | IPhone, IPad, IPod, Mobile or Tablet. |
| {DEVICE_USER_AGENT} | User agent header of requesting device. |
Macros available when running product feed retargeting:
| {PRODUCT_ID} | For retargeting ads, a specific product ID that the user viewed or clicked on. |
|---|---|
| {IOS_URL} | Product-specific iOS deeplink URL for a given product ID. |
| {ANDROID_URL} | Product-specific Android deeplink URL for a given product ID. |
An example of what your Click URL template might look like:
http://your-tracking-service.com/liftoff/click?idfa=${IDFA}&google_aid=${GOOGLE_AID}&liftoff_tracking_token=${TRACKING_TOKEN}&...
Attribute installs and events to Liftoff
We strongly recommend attributing installs and events based on the user's Device ID as it is a much more reliable method than using IP address or other techniques.
In order to attribute installs and post-install events to Liftoff, you will need to store the device ID (IDFA / Google AID) and Tracking Token for each user that Liftoff sends to your Click URL. You can then redirect the user to your app's App Store / Google Play page.
For each install or post-install event that you receive, you can then determine if that event is from a Liftoff-driven user by checking if there is a click from Liftoff with the same device ID. When there is a corresponding click from Liftoff, you would then report this event to us using our provided postback URL template.
Send event postbacks to Liftoff
For each install and event that is attributed to Liftoff, fill out the following template with the relevant user and event information by replacing each macro with its value, and then use the completed URL to send this information back to Liftoff with a GET request.
Postback URL template:
http://analytics.liftoff.io/customer_tracker/v1/{APP_ID}/events?third_party_tracking_token={tracking_token}&...
NOTE: Your postback URL contains an app-specific Liftoff App ID (APP_ID),
so if you have multiple apps make sure you use the corresponding URL/ID for
each app.
The following macros are required and must be completed for every postback:
| {tracking_token} | the unique token we sent you for this user in the click URL. |
|---|---|
| {client_ip} | The device's IP address. |
| {idfa} | Apple's identifier for advertising (empty for Android). |
| {google_aid} | Google Play advertising identifier (empty for iOS). |
| {event_name} | The name of the event that the postback corresponds to (e.g. "install", "purchase"). For installs, it should be "install". Please do not use programmatically generated strings as event names; instead, use hard-coded strings such as "signup" that describe a general point in your application's user flow. |
| {event_timestamp} | The timestamp that the event occurred at, in seconds since epoch (e.g. "1407259958"). Liftoff will default to the current timestamp if this parameter is omitted or contains an invalid value. |
| {platform} | Either "ios" or "android". |
The following macro is only required if you plan to support impression-based attribution (viewthrough):
| {is_viewthrough} | "1" when you have attributed this event to Liftoff because of an impression; "0" when you have attributed this traffic via a click. |
|---|
These macros are optional, but please include if you support them:
| {app_version} | The version of your app this event was triggered in. |
|---|---|
| {bundle_id} | The bundle ID of your app (e.g. "com.acme.ios"). |
| {os_version} | The version of iOS or Android the user is running. |
| {is_attributed} | "true" if the event is attributed to one of our clicks; "false" otherwise. This parameter is helpful in cases where you are sending us postbacks for all events, not just ones that are attributed to us. If we are only receiving postbacks for users we sent, this should always be "true". |
| {do_not_track} | "true" for users who have opted-out of ad tracking in iOS or Android, else "false". Liftoff will default to false if this parameter is omitted. |
| {revenue} | Non-zero for events which have a transaction amount associated with them. This allows us to optimize directly for revenue. |
| {currency_code} | 3-letter ISO 4217 currency code for the associated revenue (e.g. "USD". A full list of currency codes can be found here). |
| {is_first_event} | Whether this is the first time this event has been triggered for this user (e.g. "true" for a user's first in-app-purchase, but "false for their second). |
| {install_timestamp} | The timestamp the corresponding install occurred at, in seconds since epoch (e.g. "1407259598"). Note that this is not the same as the time the event occurred at. |
Extra Considerations
Viewthrough
When supporting impression-based attribution, you will naturally need to provide
us with impression tracking URLs in addition to your click URLs. Impression
notifications are sent either S2S or via client-side tracking pixels, so you
should not attempt to redirect the user as documented above for click URLs.
Liftoff also requires that you properly set the is_viewthrough flag on
postbacks to perform proper attribution internally.
Retargeting
When running retargeting campaigns, your click URLs should deeplink directly to your app when the user has already installed the app and fallback to the app store in case they do not. This is typically handled with a JavaScript redirect on a landing page. There are, however, many nuances to platform-specific deep linking and universal links. While Liftoff can offer sample landing pages and/or general guidance, we strongly encourage independently researching and testing your deep linking solution.
Testing
Once you are setup for all three of these steps (click redirection, attribution and event postbacks), Liftoff will perform end-to-end testing to ensure that each step in the process is working properly. Please contact us when you are ready to start testing your integration.