Apple Search Ads Attribution with Measure Session

Using the TUNE SDK for iOS 3.2+, we attribute installs with Apple Search Ads (previously iAD) as outlined in our Apple Search Ads integration.

In order for our Measurement API to be able to attribute installs to Apple Search Ads with measure session (SDK-less implementation), it requires that:

  1. Your apps collect the iAd attribution value along with the iAd impression timestamp and send it to your servers, and
  2. Your servers include the iAd attribution value when notifying TUNE to measure the install.

When the request to measure a session for a new user includes the iAd attribution value, our Measurement API will use the value during the attribution process accordingly.

Collecting the Search Ads Attribution Value

To enable your app for Search Ads attribution, follow these three steps:

    1. Add the iAd framework to the Xcode project file for your app.
    2. Import the iAd headers in the file containing your attribution code.
#import <iAd/iAd.h>
    1. Check for iAd attribution, and use the result in your campaign reporting.
if( [UIApplication sharedApplication] && [ADClient class] ) {
    // for devices >= 7.1
    ADClient *adClient = [ADClient sharedClient];
    
#ifdef __IPHONE_9_0
    if( [adClient respondsToSelector:@selector(requestAttributionDetailsWithBlock:)] ) {
        [adClient requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
            NSDictionary *iAdCampaignInfo = attributionDetails[@"Version3.1"];
            
            if( error.code == ADClientErrorLimitAdTracking ) {
                // iAd attribution info not available
            } else if( error ) {
                // iAd attribution info not available
            } else {
                // iOS 7.1
                BOOL appInstallationWasAttributedToiAd = iAdCampaignInfo[@"iad-attribution"] != nil && [iAdCampaignInfo[@"iad-attribution"] boolValue];
                if(appInstallationWasAttributedToiAd) {
                    NSDateFormatter *formatter = [NSDateFormatter new];
                    formatter.dateFormat = @"yyyy-MM-dd'T'HH:mm:ssZ";
                    
                    // iOS 8
                    NSString *strImpressionDate = nil;
                    if( iAdCampaignInfo[@"iad-impression-date"] ) {
                        NSDate *iAdImpressionDate = [formatter dateFromString: iAdCampaignInfo[@"iad-impression-date"]];
                        // string representation of iAd impression date double value
                        strImpressionDate = [NSString stringWithFormat:@"%ld", (long)round([iAdImpressionDate timeIntervalSince1970])];
                    }
 
                    // iOS 9
                    if( iAdCampaignInfo[@"iad-campaign-id"] ) {
                        // TODO: include campaign id -- Partner Campaign -- publisher_sub_campaign_ref
                    }
                    if( iAdCampaignInfo[@"iad-campaign-name"] ) {
                        // TODO: include campaign name -- Partner Campaign -- publisher_sub_campaign_name
                    }
                    if( iAdCampaignInfo[@"iad-org-name"] ) {
                        // TODO: include org name -- Partner Publisher -- publisher_sub_publisher_ref
                    }
                    if( iAdCampaignInfo[@"iad-lineitem-id"] ) {
                        // TODO: include line item id -- Partner Ad -- publisher_sub_ad_ref
                    }
                    if( iAdCampaignInfo[@"iad-lineitem-name"] ) {
                        // TODO: include line item name -- Partner Ad -- publisher_sub_ad_name
                    }
                    if( iAdCampaignInfo[@"iad-creativeset-id"] ) {
                        // TODO: include creative id -- Partner Placement -- publisher_sub_placement_ref
                    }
                    if( iAdCampaignInfo[@"iad-creativeset-name"] ) {
                        // TODO: include creative name -- Partner Placement -- publisher_sub_placement_name
                    }
                    NSString *strClickDate = nil;
                    if( iAdCampaignInfo[@"iad-click-date"] ) {
                        NSDate *iAdClickDate = [formatter dateFromString: iAdCampaignInfo[@"iad-click-date"]];
                        // string representation of iAd click date double value
                        strClickDate = [NSString stringWithFormat:@"%ld", (long)round([iAdClickDate timeIntervalSince1970])];

                        // TODO: include click date -- iad_click_date
                    }
                    NSString *strConversionDate = nil;
                    if( iAdCampaignInfo[@"iad-conversion-date"] ) {
                        NSDate *iAdConversionDate = [formatter dateFromString: iAdCampaignInfo[@"iad-conversion-date"]];
                        // string representation of iAd conversion date double value
                        strConversionDate = [NSString stringWithFormat:@"%ld", (long)round([iAdConversionDate timeIntervalSince1970])];

                        // TODO: include conversion date -- iad_conversion_date
                    }

                    // iOS 10
                    if( iAdCampaignInfo[@"iad-keyword"] ) {
                        // TODO: include search keyword -- Partner Keyword -- publisher_sub_keyword_ref
                    }
                    if( iAdCampaignInfo[@"iad-adgroup-id"] ) {
                        // TODO: include adgroup id -- Partner Ad Group -- publisher_sub_adgroup_ref
                    }
                    if( iAdCampaignInfo[@"iad-adgroup-name"] ) {
                        // TODO: include adgroup name -- Partner Ad Group -- publisher_sub_adgroup_name
                    }

                    // iOS 11
                    if( iAdCampaignInfo[@"iad-conversion-type"] ) {
                        // TODO: include conversion type -- Event Type -- event_type_ref
                    }
                    if( iAdCampaignInfo[@"iad-keyword-matchtype"] ) {
                        // TODO: include keyword matchtype -- Partner Matchtype -- publisher_sub_match_type_ref 
                    }
 
                    // inform your server that:
                    // 1) iad_attribution = 1
                    // 2) impression_datetime = strImpressionDate
                    // 3) any additional iAd params as may be available in iAdCampaignInfo dictionary
                }
            }
        }];
    } else
#endif
    if( [adClient respondsToSelector:@selector(lookupAdConversionDetails:)] ) {
        // device is iOS 8.0
        [[ADClient sharedClient] lookupAdConversionDetails:^(NSDate *appPurchaseDate, NSDate *iAdImpressionDate) {
            BOOL appInstallationWasAttributedToiAd = (iAdImpressionDate != nil);
            if(appInstallationWasAttributedToiAd) {
                // string representation of iAd impression date double value
                NSString *strImpressionDate = [NSString stringWithFormat:@"%ld", (long)round( [iAdImpressionDate timeIntervalSince1970])];
                
                // inform your server that:
                // 1) iad_attribution = 1
                // 2) impression_datetime = strImpressionDate
            }
        }];
    } else {
        // device is iOS 7.1
        [adClient determineAppInstallationAttributionWithCompletionHandler:^(BOOL appInstallationWasAttributedToiAd) {
            if(appInstallationWasAttributedToiAd) {
                // inform your server that: iad_attribution = 1
            }
        }];
    }
}

 

Including Search Ads Attribution with Measure Session

Include the Search Ads attribution data dictionary as part of the post data json using the key "iad" sent with:

  • the very first session request, if available before the request has been fired.

NOTE: The old way for firing a "GET" request does not support newer params available in the Search Ads info, so we recommend that "POST" requests should be used.

Request URL with SearchAds Info Example

Very First Session Request:

https://001.engine.mobileapptracking.com/serve?&action=session&advertiser_id=011&package_name=edu.self.AtomicDodgeBallLite&response_format=json&sdk=ios&...

Request POST data JSON with SearchAds Attribution Info Example

{
  "iad": {
    "Version3.1": {
      "iad-lineitem-id": "32132132",
      "iad-keyword": "atomic dodge",
      "iad-keyword-matchtype": "broad",
      "iad-org-name": "TUNE, Inc.",
      "iad-conversion-date": "2012-11-09T23:21:27Z",
      "iad-attribution": "true",
      "iad-conversion-type": "download",
      "iad-adgroup-name": "my_adgroup_1",
      "iad-creativeset-name": "my_creativeset_1",
      "iad-campaign-id": "22334455",
      "iad-adgroup-id": "12345678",
      "iad-lineitem-name": "my_lineitem_1",
      "iad-campaign-name": "my_ad_campaign_1",
      "iad-click-date": "2016-10-31T19:42:04Z"
    }
  }
}

 

Search Ads attribution data dictionary

iad_adgroup_id Partner AdGroup Ref Unique identifier for the iAd Ad Group.
iad_adgroup_name Partner AdGroup Name Name of the iAd Ad Group.
iad_attribution Partner Indicates if the app install is attributed to iAd: 1 if appInstallationWasAttributedToiAd is True; else 0 (False).
iad_campaign_id Partner Campaign Ref Unique identifier for the iAd campaign.
iad_campaign_name Partner Campaign Name Name of the iAd campaign.
iad_campaign_org_name Partner Publisher Name of the iTunes Connect organization (associated with the iAd campaign).
iad_conversion_type Event Type Download or ReDownload (as returned by the API with the above).
iad_click_date Ad Click Date Unix timestamp of the iAd click datetime (as returned by the API with the above).
iad_conversion_date Install Conversion Date Unix timestamp of the iAd conversion datetime (as returned by the API with the above).
iad_creativeset_id Partner Placement Ref Unique identifier for the iAd creative/advertisement.
iad_creativeset_name Partner Placement Name Name of the iAd creative/advertisement.
iad_keyword Partner Keyword Keyword used during the app search.
iad_keyword_matchtype Partner Matchtype Keyword Matchtype used; Broad or Exact.
iad_line_id Partner Ad Ref Unique identifier for each line item in an iAd campaign.
iad_line_name Partner Ad Name Name of the line item in an iAd campaign.
impression_datetime Ad Impression Date Unix timestamp of the iAd impression datetime (as returned by the API with the above).
Have a Question? Please contact support@tune.com for technical support.