iOS SDK integration guide for marketers

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, 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 overview

waitForATTUserAuthorization enables you to configure how long should the SDK defer sending data to the AppsFlyer servers, and wait for ATT status.

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/the app is killed during the timeout:
  • The timer is restarted on the next app launch.
  • Cached events are lost.

You can choose to customize the ATT prompt. A message that clearly states the purpose of the request might help increase the opt-in rates for users.

Note 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. To learn more about user privacy and data use, click here.

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

To view some external examples of ATT prompts, click here.

SKAN is a class used by iOS that validates 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 signed by 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.
• AppsFlyer SDK automatically calls the necessary SKAN APIs.
• Make sure to disable SKAN calls in other SDKs when relying 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. 

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 raw data and dashboard. For more details click here. 

For developer instructions, see logging revenue.

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 double duplicate event reporting.

If your app belongs to a vertical such as travel, gaming, or eCommerce, see our list of recommended in-app events per vertical.

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

Note: Device detection and redirection do not require the AppsFlyer SDK. However, the SDK is required for 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 up deep linking with OneLink.

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). 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 Unified Deep Linking (UDL).

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 deferred deep linking to learn more.

AppsFlyer supports the measurement of push notification campaigns from all vendors and can also support developers who use Google Cloud Messaging or Apple push notification services directly. The conversions, defined as app opens originating from push notification messages, display in the Retargeting dashboard.

You can use OneLink to measure user re-engagement via push notifications. See our guide on measuring push notification re-engagement campaigns.

To learn how to set up uninstall measurement, read here.

If you want to receive a confirmation that the SDK started successfully and notified AppsFlyer servers, implement the startWithCompletionHandler handler. You can then apply logic to handle the success or failure of the SDK launch.

Implementation example

[[AppsFlyerLib shared] startWithCompletionHandler:^(NSDictionary<NSString *,id> *dictionary, NSError *error) {
        if (error) {
            NSLog(@"%@", error);
            return;
        }
        if (dictionary) {
            NSLog(@"%@", dictionary);
            return;
        }
    }];

 AppsFlyerLib.shared()?.start(completionHandler: { (dictionnary, error) in
            if (error != nil){
                print(error ?? "")
                return
            } else {
                print(dictionnary ?? "")
                return
            }
        })

In the event that an error occurs during the request listener, an error code and string description are provided, as indicated in the table that follows.

The setAdditionalData API allows you to add custom data to events sent from the SDK. Typically it is used to integrate on the SDK level with several external partner platforms, including Segment, Adobe, and Airship.

setAdditionalData code example:

NSDictionary* customDataMap = [[NSDictionary alloc] initWithObjectsAndKeys:@"value_of_param_1", @"custom_param_1", nil];
[[AppsFlyerLib shared] setAdditionalData:customDataMap];

let customDataMap: [AnyHashable: Any] = [
  "custom_param_1" : "value_of_param_1"
]
AppsFlyerLib.shared().customData = customDataMap

App owners using Universal Links for deep linking (without OneLink), and have a domain associated with their app can attribute sessions initiated via this domain using the appendParametersToDeepLinkingURL method.

For example, a user searches Google and clicks on your domain, www.example.com:

• If the user doesn’t have the app installed, they are directed to the website (www.example.com).
• If the user has the app installed on their device, they are deep linked into the app associated with www.example.com. The session is attributed to the media source (pid parameter) specified in appendParametersToDeepLinkingURL.

See the iOS SDK reference for additional information.

Note: Smart Banners help app owners convert website visitors to app users.

By default, at least 5 seconds must pass between two app launches to count as two separate sessions (more about counting sessions).

Use the following API to set the minimum time between sessions:

[AppsFlyerLib shared].minTimeBetweenSessions = <your_custom_time_in_seconds>;

AppsFlyerLib.shared().minTimeBetweenSessions = <your_custom_time_in_seconds>

Setting a high value to the custom time between launches may badly impact APIs relying on session data, such as deep linking.

Unavailable in iOS.

Some 3rd party services such as email service providers wrap links in emails with their own click recording domains. Some even allow you to set your own click recording domains. If OneLink is wrapped in such domains, it might limit its functionality.

To overcome this issue you can use the setResolveDeepLinkURLs API. Use this API to get the OneLink from click domains that launch the app. Make sure to call this API before SDK initialization.

For example, you have three click domains that redirect to your OneLink which is https://mysubdomain.onelink.me/abCD. Use this API to get the OneLink that your click domains redirect to. This API method receives a list of domains that the SDK resolves.

[AppsFlyerLib shared].resolveDeepLinkURLs = @[@"example.com",@"click.example.com"];

AppsFlyerLib.shared().resolveDeepLinkURLs = ["example.com", "click.example.com"]

The code above allows you to use your click domain while preserving OneLink functionality. The click domains are responsible for launching the app. The API, in turn, gets the OneLink from these click domains, and then you can use the data from this OneLink to deep-link and customize user content.

With AppsFlyer, you can record push notifications as part of retargeting campaigns. For more information on push notification measurement, read here.

Allowing your existing users to invite their friends and contacts as new users to your app, can be a key growth factor for your app. With AppsFlyer, you can attribute and record installs that originate from user invites within your app.

For details, see the User Invite Attribution article.

Note! Cross-promotion by IDFV requires SDK 6.0.2+. IDFV is collected automatically and no further action is required by the developer.

An AppsFlyer unique ID is created for every new install of an app. You can use this ID for various purposes:

• Send server-to-server in-app events.
• Match it with user records in your backend systems.
• Map entries when merging data from pull and push API.

Use the following API to obtain the unique ID:

NSString *appsflyerId = [AppsFlyerLib shared].getAppsFlyerUID;

let appsflyerId = AppsFlyerLib.shared().getAppsFlyerUID()

To set your Customer User ID:

[AppsFlyerLib shared].customerUserID = @"my user id";

AppsFlyerLib.shared().customerUserID = "my user id"

In iOS, the Customer User ID needs to be set with every app launch. We recommend setting the Customer User ID early in the app flow, as it is only associated with events reported after its setup:

• If setCustomerUserId is called before calling start, the Customer User ID appears in the raw data reports for installs and for events.
• If it is set after, the Customer User ID is only associated with events that are recorded after setting the Customer User ID.

To avoid setting the Customer User ID value again beyond the first launch, and to reduce calls to your server to get the customer user ID, you can check if its value is empty or not by using:

NSString *customerUserID = [AppsFlyerLib shared].customerUserID;

let customerUserID = AppsFlyerLib.shared().customerUserID

For more information about the Customer User ID, click here.

You can delay the SDK Initialization until the Customer User ID is set. This is useful if its important for you that install and event data contain your customer user ID.

Implement the following code:

- (void)applicationDidBecomeActive:(UIApplication *)application {
    NSString *customUserId = [[NSUserDefaults standardUserDefaults] stringForKey:@"customerUserId"]; // Your custom logic of retrieving CUID
    if (customUserId != nil && ![customUserId  isEqual: @""]) {
        [AppsFlyerLib shared].customerUserID = customUserId; // Set CUID in AppsFlyer SDK for this session
        [[AppsFlyerLib shared] start]; // Start
    }
}

func applicationDidBecomeActive(_ application: UIApplication) {
        let customUserId = UserDefaults.standard.string(forKey: "customUserId")  //  your logic to retrieve CUID
        if(customUserId != nil && customUserId != ""){
            AppsFlyerLib.shared().customerUserID = customUserId // Set CUID in AppsFlyer SDK for this session
            AppsFlyerLib.shared().start() // Start
        }
    }

To learn more about delaying the SDK initialization until the Customer User ID is available, go here.

You may want to delay initializing the SDK and sending data until the user gives consent (for example, GDPR or COPPA consent).

Note: This is unrelated to ATT introduced in iOS 14. 

To delay initializing the SDK:

1. Prevent the session from being sent on background-foreground transition. In a sendLaunch() method (that is called on every applicationDidBecomeActive (as per section 3.3), wrap call to start with a condition check. For example:
   
   

   -(void)sendLaunch:(UIApplication *)application {
       if (consent_given) { // check the condition
           [[AppsFlyerLib shared] start]; // Start
       }
   }

2. Send the session as soon as the reason for delaying is no longer relevant (right after condition changes). Call start when you are ready to send the first session data. For example:
   
   

   ...
   consent_given = YES; // change the condition
   [[AppsFlyerLib shared] start]; // Start
   ...

In some extreme cases, you might want to shut down all SDK data logging due to legal and privacy compliance. This can be achieved with the isStopped property. Once this property is set to true, the SDK stops functioning and no longer communicates with AppsFlyer servers.

There are several different scenarios for user opt-out. We highly recommend following the exact instructions for the scenario that is relevant for your app.

[AppsFlyerLib shared].isStopped = true;

AppsFlyerLib.shared().isStopped = true

In any event, the SDK can be reactivated by calling the same API, by passing false.

Use this API during the SDK Initialization to explicitly anonymize a user install, events and sessions:

[AppsFlyer shared].anonymizeUser = YES;

AppsFlyerLib.shared().anonymizeUser = true

Logging data can be restarted by setting anonymizeUser to false.

Use the strict mode SDK to completely remove IDFA collection functionality and AdSupport framework dependencies (for example, when developing apps for kids).

Note: IDFV remains available.

In your Podfile, replace the AppsFlyerLib dependency with:

pod 'AppsFlyerFramework/Strict','6.2.3'

To disable the AdSupport and iAd frameworks, the SDK provides the following setters:

• disableCollectASA = true. Learn more
• disableAdvertisingIdentifier = true. Learn more

To disable ad frameworks:

[AppsFlyerLib shared].disableCollectASA = YES
[AppsFlyerLib shared].disableAdvertisingIdentifier = YES;

AppsFlyerLib.shared().disableCollectASA = true
AppsFlyerLib.shared().disableAdvertisingIdentifier = true

In some cases, advertisers may want to stop sharing user-level data with ad networks/partners for specific users. Reasons for this include: 

• Privacy policies such as CCPA or GDPR
• User opt-out mechanisms
• Competition with some partners (ad networks, third parties)

Data sharing with partners is controlled via the setSharingFilterForPartners method.