Accessing AppsFlyer Attribution / Conversion Data from the SDK - iOS (Deferred Deeplinking)

AppsFlyer allows you to access the user attribution data in real time directly at the SDK level. It enables you to customize the landing page a user sees on the very first app open after a fresh app install. This is commonly referred to as “deferred” deeplinking. This is very common on the web, however there is a big challenge doing this in the mobile app ecosystem. Luckily, AppsFlyer provides support for all cases and platforms.

Sending a new app user to a deeplink on install is very similar to using app deeplinking custom URL Scheme (iOS) for users that have already installed your app. 

For example:

Consider a user who has just clicked on a HotelTonight’s Google Adwords ad for a "Hotels New York" search.  The user is first sent to Google Play/App-Store to download the app and upon first app open the user lands directly on the Hotels in New York page. By accessing the attribution data provided by AppsFlyer, the application will receive the exact campaign and keywords used to drive that user/install.

Besides the enhanced experience and improved conversion, this functionally enables sophisticated context based campaigns such as providing the user with a credit/bonus for installing and using the app. For example: Instead of "Click to install" campaigns to "Install and get $50 credit for booking". These campaigns not only improve the click to install conversion, but also improve the conversion to paying users. These campaigns can improve overall ROI by 2X-5X!

AppsFlyer's NativeTrack™ SDK is performing server side tracking. That means that the conversion track is processed and available on AppsFlyer’s servers. Accessing the attribution data from AppsFlyer's SDK might take few seconds from the first app open.

NOTES:

• According to Facebook's privacy policy, AppsFlyer (or any other 3rd party mobile measurement partner) cannot provide user-level attribution for Facebook installs unless you accept Facebook's Terms of Service. More info here.
  
  If you choose not to accept the Terms of Service, Facebook Mobile Ads installs are categorized as ‘Organic’ and you are unable to receive the user level data for Facebook installs.
• Accessing the attribution data to implement deferred deeplinking is applicable for the user's first launch after the install.  To implement deeplinking for users who already have the app installed, see here.  

SDK Implementation: 

NOTE: AppsFlyer iOS SDK 2.5.3.8 and above.

The delegate below is used if you want to access AppsFlyer's conversion data from the SDK.

(void) onConversionDataReceived:(NSDictionary*) installData;

onConversionDataReceived has the attribution data of the install. You can use this function to:

1. Deferred Deeplinking - customize your app’s landing page to user that had entered the app for the first time.
2. Get install attribution data for different events during the user's lifetime within your app

For example:

A user downloads and launches your app for the first time after seeing your ad for red shoes on Facebook. To send the user directly to the red shoes page in your app, use onConversionDataReceived

To access AppsFlyer's conversion data from the iOS SDK implement the AppsFlyerTrackerDelegate protocol: 

@protocol AppsFlyerTrackerDelegate <NSObject>
@optional

- (void) onConversionDataRequestFailure:(NSError *)error;
@end

Example:

AppDelegate.h

#import "AppsFlyerTracker.h"
@interface AppDelegate : UIResponder<UIApplicationDelegate, AppsFlyerTrackerDelegate> {
   ...
}

AppDelegate.m

- (BOOL)application:(UIApplication ​*)application didFinishLaunchingWithOptions:(NSDictionary*​)launchOptions {
   [AppsFlyerTracker sharedTracker].appsFlyerDevKey = @"[MY_DEV_KEY]";
   [AppsFlyerTracker sharedTracker].appleAppID = @"123456789";
 
// Load conversion data and deep-link tracking

   [AppsFlyerTracker sharedTracker].delegate = self;

   return YES;
}

-(void)applicationDidBecomeActive:(UIApplication *)application
{
   [[AppsFlyerTracker sharedTracker] trackAppLaunch];
}
-(void)onConversionDataReceived:(NSDictionary*) installData {

    id status = [installData objectForKey:@"af_status"];
    if([status isEqualToString:@"Non-organic"]) {
        id sourceID = [installData objectForKey:@"media_source"];
        id campaign = [installData objectForKey:@"campaign"];
        NSLog(@"This is a none organic install. Media source: %@  Campaign: %@",sourceID,campaign);
    } else if([status isEqualToString:@"Organic"]) {
        NSLog(@"This is an organic install.");
    }
}
-(void)onConversionDataRequestFailure:(NSError *) error {
    NSLog(@"%@",error);
}

Output example:

{
"af_status": "Non-organic",
"media_source": "tapjoy_int",
"campaign": "July4-Campaign",
"agency": "starcomm",
"af_siteid": null,
"af_sub1": "subtext1",
"af_sub2": null,
"af_sub3": null,
"af_sub4": null,
"af_sub5": null,
"freehand-param": "somevalue",
"click_time": "2014-05-23 20:11:31",
"install_time": "2014-05-23 20:12:16.751"
}

Available Keys in Attribution Response:

The returned conversion data consists on ALL the parameters on the original tracking link and some additional server parameters created on the time of click or install.

Since the conversion data is reliant on the tracking link, it means that different sources and tracking links may produce different conversion data parameters.

The onConversionDataReceived function is called every time the app is launched.
There are 3 possible outcomes depending on the type of the install:

1. Non organic install - returns the original attribution data of the install (see the examples below).

2. Organic install (or re-install) - returns "organic install"

3. Re-attribution - returns the re-attribution conversion details.

Examples:

Facebook Attribution Response: 

NOTES: 

• There is no tracking link for Facebook campaigns.
• Deeplinks defined in the Facebook campaign are not available in getConversionData response.  To implement deferred deeplinking, additional logic must be applied for Facebook campaigns according to the data which is available in getConversionData response, such as, campaign, adset, adgroup.

{
   "media_source":"Facebook Ads",
   "campaign":"T:App Install_A:ALL",
   "adset":"T:App Install_M:iOS_O:ALL_L:DE-DE_A:ALL",
   "adgroup":"T:App Install_M:iOS_O:ALL_L:DE-DE_A:ALL_Banne",
   "campaign_id":"6074766693717",
   "af_status":"Non-organic",
   "agency":null,
   "af_sub3":null,
   "af_siteid":null,
   "adset_id":"6074767207317",
   "is_fb":true,
   "click_time":"2017-07-17 16:23:18",
   "iscache":false,
   "ad_id":"6078076656717",
   "af_sub1":null,
   "is_paid":true,
   "af_sub4":null,
   "adgroup_id":"6074821181517",
   "is_mobile_data_terms_signed":true,
   "af_channel":"Facebook",
   "af_sub5":null,
   "install_time":"2017-07-18 15:10:50.190",
   "af_sub2":null
}

2. Regular AppsFlyer Tracking Link Response Example (Not Facebook):

Install generated using the following tracking link:

http://app.appsflyer.com/id578915438?pid=tapjoy_int&c=July4-2014&af_prt=starcomm&af_siteid=57&af_sub1=subtext1&freehand-param=somevalue

Attribution response:

{
   "media_source":null,
   "campaign":"Glispa_KR",
   "adset":null,
   "adgroup":null,
   "campaign_id":null,
   "af_cost_currency":"USD",
   "af_status":"Non-organic",
   "agency":"ECHOMARKETING",
   "af_sub3":null,
   "af_cost_model":"CPI",
   "af_siteid":"1777236",
   "af_dp":"app://home",
   "adset_id":null,
   "click_time":"2017-07-18 14:48:42.896",
   "cost_cents_USD":"0",
   "iscache":true,
   "af_cpi":null,
   "af_sub1":"CD48704_",
   "af_click_lookback":"1d",
   "af_sub4":null,
   "site_id":"1777236",
   "adgroup_id":null,
   "tag":"43fafd60-76ad-4a8f-9d1d-************",
   "orig_cost":"0.0",
   "af_prt":"ECHOMARKETING",
   "af_sub5":null,
   "install_time":"2017-07-18 15:09:06.014",
   "af_sub2":"Glispa_KR_G001_iOS",
   "clickID":"3gggBgAw2Bvxa8gR56ZA8Y3qjUy2gPkFgP6rA96s4eKqAAAAAA"
}

 NOTE: Keys order may vary. Additional keys might be added without notice.

Agency Transparency Support on Get Conversion Data

When agency transparency is disabled, the Get Conversion Data Callback returns media source null and agency <agency name>.

Example:

{
"af_status": "Non-organic",
"media_source": null,
"campaign": "July4-Campaign",
"agency": "starcomm",
"af_siteid": null,
"af_sub1": "subtext1",
"af_sub2": null,
"af_sub3": null,
"af_sub4": null,
"af_sub5": null,
"freehand-param": "somevalue",
"click_time": "2014-05-23 20:11:31",
"install_time": "2014-05-23 20:12:16.751"
}

When agency transparency is enabled, the Get Conversion Data Callback returns the attributed media source and agency <agency name>.

Example:

{
"af_status": "Non-organic",
"media_source": tapjoy_int,
"campaign": "July4-Campaign",
"agency": "starcomm",
"af_siteid": null,
"af_sub1": "subtext1",
"af_sub2": null,
"af_sub3": null,
"af_sub4": null,
"af_sub5": null,
"freehand-param": "somevalue",
"click_time": "2014-05-23 20:11:31",
"install_time": "2014-05-23 20:12:16.751"
}