At a glance: Work with your mobile or CTV app developer to integrate and install the SDK into Android or iOS apps. Once basic integration tasks are complete, your app is ready for install attribution and in-app event measurement.
For a complete picture of planning the SDK integration with your app, be sure to read these articles:
- SDK integration overview
- Basic SDK integration guide (this article)
- Additional SDK integration guide
- Connected TV (CTV) and over-the-top (OTT) overview
Retrieving the dev key
Before your developer can install and integrate the SDK, you must retrieve the dev key. AppsFlyer uses the dev key to uniquely identify your account. The dev key is mandatory because it allows the SDK to securely send and retrieve data that belongs to your account.
To retrieve your dev key:
- In AppsFlyer, go to Configuration > App Settings.
- Copy your dev key, and send it to your mobile developer.
- Provide your mobile developer with the instructions to install and integrate the SDK.
Where to start the SDK?
When planning the integration of the AppsFlyer SDK, the first decision you must make is where to initialize and start the SDK within your application launch flow.
The basic rule of thumb is to have the SDK start sending data as soon as possible after launching the application.This ensures that the SDK captures the install event and all other in-app events occurring in the session.
However, in order to comply with privacy regulations such as GDPR and CCPA, it is often necessary to delay sending data to AppsFlyer until users consent to share their information.
Starting the SDK in Android
Select in what class to start the SDK
Select whether to start the SDK in the global
Application class or the
Start the SDK in the global
Applicationclass: Generally, initializing the SDK in the global
Applicationclass/subclass is a good practice because the
Applicationclass is loaded and initialized before any app UI is displayed. This ensures that the SDK can start in any scenario, including deep linking.
Start the SDK in an
Activityclass (deferred start) to allow users to opt-in to data sharing. This is because obtaining user consent requires a user interface (UI) rendered in an
Select the opt-out/in scenario
Select an opt-out scenario outlining how to call
start in a way that complies with privacy regulations such as GDPR and CCPA. For example, select between Opt-out at installation scenario, one-time opt-out scenario, or preventing data sharing with third parties scenario.
For more information on the opt-out scenarios available, including code samples, see Opt-in and Opt-out scenarios.
Android developer instructions
Starting the SDK in iOS
Delay the SDK start in iOS
An important consideration when planning how to start the SDK is whether to delay
start until user consent is granted.
The SDK provides the
waitForATTUserAuthorization method, which enables you to configure how long the SDK should wait for user consent before sending data to the AppsFlyer servers.
For more information on the method data flow and its interaction with the iOS ATT framework, see the Configure App Tracking Transparency (ATT) support section.
Select the opt-out/in scenario
Select an opt-out scenario outlining how to call
start in a way that complies with privacy regulations such as GDPR and CCPA. For example, select between the Opt-out at installation scenario, the one-time opt-out scenario, or preventing data sharing with third parties scenario.
For more information on the different opt-out scenarios available, see Opt-in and Opt-out scenarios.
iOS developer instructions
Share with your developer the following information:
- How long in seconds is the timeout before sending data to AppsFlyer?
- Which opt-in/opt-out scenario to use?
- Developer Links:
- Starting the iOS SDK for developer guide and reference on how to start the SDK.
Configure App Tracking Transparency (ATT) support for information on the
waitForATTUserAuthorizationmethod data flow and how it interacts with the iOS ATT framework
Enabling App Tracking Transparency (ATT) support for developer guide and reference on
The SDK collects identifiers for attribution purposes. To ensure that installs are recorded and attributed correctly, review and follow these guidelines.
Unique identifier for installs
An AppsFlyer ID is automatically created for every new app install. No action is required by the marketer.
You can use this identifier to perform the following actions:
Integrate unique identifiers from your BI system with AppsFlyer
Set your own Customer user ID (CUID) in the AppsFlyer SDK to cross-reference the unique ID from your BI system with the AppsFlyer ID and other identifiers. The CUID is available in AppsFlyer raw data reports. You can also use it in postback APIs for cross-referencing with your internal IDs.
To learn more about CUID, see this article.
The following sections describe attribution considerations for Google Play Store or third-party app stores.
Attribute apps published on Google Play
Google Play Install Referrer
The Google Play Install Referrer API improves attribution accuracy, protects from install fraud, and allows secure retrieval of referral data from Google Play (for example, the app's version at the time when the app was first installed).
It is recommended that you provide your developer with instructions to add the Google Play Install Referrer API.
Starting with SDK V4.8.0, AppsFlyer automatically collects this device identifier.
Attribute apps in third-party app stores
With AppsFlyer, you can attribute installs originating from third-party app stores, such as Amazon, Opera, GetJar, Baidu, and Huawei. This allows you to promote your apps and reach larger audiences in markets where Google Play Store is not available.
AppsFlyer supports attribution in the context of third-party app stores as follows:
- IMEI or Android ID: The SDK doesn't automatically collect the IMEI or Android ID. However, if there is a need to collect these identifiers (for example, for apps in the Chinese domestic market) your developer can implement one of the following collection types:
- OAID: Attributes installs from third-party Android app stores. For more information, see the guide to implementing OAID.
- Install referrers: The SDK supports retrieval of referral data from Samsung Gallery and Huawei AppGallery.
The following sections include important information about support for iOS 14+ devices.
Configure App Tracking Transparency (ATT) support
Starting with iOS 14.5, IDFA collection requires user consent. Practically, it means IDFA access is governed by the App Tracking Transparency (ATT) framework. On iOS 14+ devices, the SDK uses the ATT framework to obtain access to the device IDFA.
For an introduction to ATT, see ATT principles.
When attribution occurs using IDFA, it's important IDFA is sent on the first launch. For this reason, the SDK provides the waitForATTUserAuthorization utility.
waitForATTUserAuthorization if you don't intend to invoke the ATT prompt.
waitForATTUserAuthorization enables you to configure how long the SDK should defer and wait for ATT status before sending data to the AppsFlyer servers.
When a user launches the app, ATT status is notDetermined. During the
waitForATTUserAuthorization timeout, the SDK queues the launch event and consecutive in-app events in-memory, similar to the way in which offline events are recorded:
- If the user consents to the ATT prompt (IDFA collection):
- The SDK adds the IDFA to cached events.
- The SDK starts and sends cached events with IDFA (without waiting for the timeout to end).
- If the user declines the ATT prompt: The SDK starts and sends cached events without IDFA (without waiting for the timeout to end).
- If the timeout ends and ATT status remains notDetermined: The SDK starts and sends cached events without IDFA.
waitForATTUserAuthorizationwill result in launches and events being sent without IDFA for iOS 14+ devices.
- If the user moves the app to the background during the timeout:
- The timer pauses until the app returns to the foreground.
- Events are cached in-memory.
- If the user shuts down the app, it is killed during the timeout:
- The timer is restarted on the next app launch.
- Cached events are lost.
Customize ATT consent dialog
You can customize the ATT prompt. A message that clearly states the purpose of the request could help increase the opt-in rates for users.
Consider the following when creating your message:
- Use wording that best explains to your users why the app is asking for user consent.
- Inform users about how their data will be used. Learn more about user privacy and data use.
Once your message is complete, provide your developer with the text and implementation instructions.
Support for SKAN attribution
To fully support SKAN attribution, upgrade to iOS SDK V6.2.3+.
SKAN is a class used by iOS to validate advertiser-driven app installations. The app install validation process involves the source app and the advertised app.
A source app is an app that participates in ad campaigns by displaying ads from an ad network. Configuring your app to display ads is not within the scope of the AppsFlyer SDK. To configure, follow the Apple instructions.
For the advertised app (the app with the AppsFlyer SDK), the AppsFlyer SKAN solution uses SKAN to provide the attribution postback while AppsFlyer collects, translates, and aggregates the data while maintaining user privacy. When the app is launched for the first time, the AppsFlyer platform uses the configuration set by the marketer to instruct the SDK how to set the SKAN conversion value.
To use the SKAN solution:
- The marketer needs to configure SKAN measurement in AppsFlyer. The developer does not have to perform any tasks.
- The AppsFlyer SDK automatically calls the necessary SKAN APIs.
- Make sure to disable SKAN calls in other SDKs if you rely on AppsFlyer for SKAN attribution.
- There is no other action or registration process required by either the developer or the marketer in the App Store.
To disable SKAN attribution, instruct your developer to disable it in the SDK.
Recording in-app events
In-app events (IAE) provide insight into what is happening in your app. Recording in-app events helps you measure KPIs like Return on Investment (ROI) and Lifetime Value (LTV). We recommend taking the time to define the events that you want to record.
Once you determine the in-app events you want to measure, send the event names and parameters to your developer, and include a link to the implementation instructions.
To learn more about in-app events, see our Rich in-app events guide.
Validate in-app purchases
The AppsFlyer SDK provides server verification for in-app purchases. Validating an in-app purchase automatically sends an in-app purchase event to AppsFlyer. Sending this event yourself creates duplicate event reporting.
See our list of recommended in-app events per vertical, for example, travel, gaming, or eCommerce.
Deep linking with OneLink
OneLink is the AppsFlyer solution for multi-platform attribution, redirection, and deep linking.
Device detection and redirection
For users without your app installed, OneLink detects the device type and redirects them to the correct destination (for example, Google Play, Apple App Store, third-party app store, or web page). This is based on your OneLink template settings. Learn more
For users with your app installed, OneLink opens the app. In addition to opening the app, you can also deep link users to a specific activity or page within the app. This requires your developer to implement Unified Deep Linking (UDL).
- UDL requires SDK V6.1+.
- Customers already using OneLink for deep linking may be using the legacy method, instead of UDL.
Deferred deep linking
For users without your app installed, OneLink detects the device type and redirects them to the correct destination: Google Play, Apple App Store, third-party app store, or web page. Once the user launches the app, you can use deferred deep linking to redirect them to a specific activity or page within the app.
This requires your developer to implement extended deferred deep linking.
- UDL requires SDK V6.1+.
- Customers already using OneLink for deferred deep linking might be using the legacy method, instead of UDL.
Accessing attribution and deep linking data
The following table describes the available methods for retrieving attribution and deep linking data:
|Method||Who is involved?||Return results||Retrieval method||Attribution data||Deep linking data||Availability|
||Typically within minutes||Backend||Y||N||Premium|
||Backend||Y||Y||Premium for raw-data reports|
Hourly reports are available within 1 - 3 hours
Cloud storage via one of the following options:
|Get conversion data (GCD)||
||Up to 5 seconds||SDK||Y||Y||All accounts|
|Unified Deep Linking (UDL)||
||Up to 1 second||SDK||N||Y||All accounts|
Note the following for iOS 14.5+ non-consenting users:
- When using UDL for paid and owned media, deep linking data is available.
- When using GCD for paid media, the data is limited and does not include attribution and deep linking details.
We recommend the following:
- Use Push API to retrieve attribution data and send it to your servers for further processing. This method waits for the data to become available, and therefore is highly accurate and close to real-time. GCD returns data in real-time, but may be inaccurate when final attribution decisions are determined after more than 5 seconds.
- Use Pull API to periodically (for example, daily) supplement real-time attribution data, and to compensate for any communication errors that might occur.
Testing your SDK integration
Once the SDK integration is complete, you can go to the AppsFlyer dashboard, and from the SDK Integration Tests page, test organic and non-organic installs, in-app events, and deep linking (retargeting). This ensures that installs and in-app events are recorded and attributed correctly.
If you need your developer to test the SDK integration, add the developer as a user in your account, so they can access the dashboard.
For testing scenarios and instructions, see SDK integration testing.