Basic SDK integration guide

For:
Marketers
Last update:

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.

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:

  1. In AppsFlyer, go to Configuration > App Settings.
  2. Copy your dev key, and send it to your mobile developer.

  3. 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, to comply with privacy preserving regulations such as GDPR and CCPA, it is often necessary to delay sending data to AppsFlyer until users consent to share their information.

Android native iOS native Unity React Native

Starting the SDK in Android native

SELECT IN WHAT CLASS TO START THE SDK

Select whether to start the SDK in the global Application class or the Activity class:

  • Start the SDK in the global Application class: Generally, initializing the SDK in the global Application class/subclass is a good practice because the Application class 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 Activity class (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 Activity class.

ANDROID DEVELOPER INSTRUCTIONS

  • Inform the developer of your decision on the following:
    • In what class - Application or Activity - to start the SDK?
    • Which opt-in/opt-out scenario to use?

Starting the SDK in Unity

Send your developer this Dev Hub article on how to start the SDK.

Starting the SDK in React Native

Send your developer this Dev Hub article on how to start the SDK.

Select your privacy preserving strategy

Select how to preserve user privacy. For example, select between stopping the SDK at installation, preventing data sharing with third parties, anonymizing user data or disabling specific identifiers.

For more information on the different opt-out scenarios available, see Opt-in and Opt-out scenarios.

Attribution

The SDK collects identifiers for attribution purposes. To ensure that installs are recorded and attributed correctly, review and follow these guidelines.

All platforms

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.

Android only

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.

GAID

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 the 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:
    • Manual collection: The app passes the IMEI or Android ID to the SDK using the setImeiData or setAndroidIdData API (see function reference in the tabs below). The SDK sends the data to AppsFlyer servers.
      Android nativeUnity

      See the Android SDK reference for:

  • 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.

iOS only

The following sections include important information about support for iOS 14+ devices.

Configure App Tracking Transparency (ATT) support

BACKGROUND

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.

iOS nativeUnity

See the Dev Hub for developer instructions for implementing ATT.

When attribution occurs using IDFA, it's important IDFA is sent on the first launch. For this reason, the SDK provides the waitForATTUserAuthorization method.

waitForATTUserAuthorization overview

 Important!

Don't call 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.

Considerations

  • Calling requestTrackingAuthorization without setting waitForATTUserAuthorization will 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:

Once your message is complete, provide your developer with the text and implementation instructions.

iOS nativeUnity

See the Dev Hub for developer instructions for customizing the ATT consent dialog.

See some external examples of ATT prompts.

Support for SKAN attribution

 

 Note

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 on 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.

iOS nativeUnityReact Native

To disable SKAN attribution use disableSKAdNetwork

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.

All platforms

Record revenue

You can send revenue with any in-app event. Make sure you use the af_revenue parameter to include revenue. It is the only event parameter that AppsFlyer counts as real revenue on the dashboard and in raw data reports. Learn more.

Android nativeiOS nativeUnity

For developer instructions on defining revenue events see here.

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.

Industry verticals

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.

All platforms

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

Deep linking

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).

Note:

  • UDL requires SDK V6.1+.
  • Customers already using OneLink for deep linking may be using the legacy method, instead of UDL.

See our guide on setting Deep linking and deferred deep linking.

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.

Note:

  • UDL requires SDK V6.1+.
  • Customers already using OneLink for deferred deep linking might be using the legacy method, instead of UDL.

See our guide on setting Deep linking and deferred deep linking.

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
Push API • Marketer • Back-end developer Typically within minutes Backend Y N Premium
Pull API • Marketer • Back-end developer • Periodic (not real-time). • You can schedule raw-data report downloads. Backend Y Y Premium for raw-data reports
Data Locker • Marketer • Back-end developer Hourly reports are available within 1 - 3 hours Cloud storage via one of the following options: • AppsFlyer-owned bucket on AWS • Storage owned by you (AWS or GCS) Y Y Premium
Get conversion data (GCD) • Marketer • Mobile  developer See developer documentation Up to 5 seconds SDK Y Y All accounts
Unified Deep Linking (UDL) • Marketer • Mobile developer See developer documentation 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.

 Tip

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.

Note: When performing attribution tests, register a test device (Android or iOS) to make sure each install is recorded as a new install. A registered test device prevents installs from being recorded as reinstalls.

See also