Article

Setting up Apple Search Ads Attribution

Identify meaningful metrics by retrieving the attribution dictionary.

Overview

The attribution dictionary contains attribution data retrieved from user interaction with ads originating from an Apple Search Ads campaign. To retrieve the attribution dictionary, perform the following process in sequence.

Add the iAd Framework to Your Xcode Project

The iAd framework is bundled with Xcode. You need to add it to the Xcode project file for your app.

  1. From Xcode, go to your target view and select General.

  2. Scroll down to the Linked Frameworks and Libraries section and click the plus (+) icon.

  3. In the dropdown menu, choose iAd.framework, and then click Add.

  4. Import iAd Headers into your app. These headers are typically in the file that contains your attribution code. The header file corresponds to the iOS version for which you compile your app in Xcode. Apple Search Ads attribution requires iOS 10.0 and later.

For more information about frameworks, see Embedding Frameworks in an App.

Retrieve the Attribution Dictionary

Implement the requestAttributionDetails(_:) method to retrieve the dictionary that contains the attribution object. Next, check for Apple Search Ads attribution, such as at first open or when registration is complete. Store the data locally so you don't need to repeat the method call.

// Check for iOS 10 attribution implementation
if ([[ADClient sharedClient] respondsToSelector:@selector(requestAttributionDetailsWithBlock:)]) { 
NSLog(@"iOS 10 call exists"); 
[[ADClient sharedClient] requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) { 
// Look inside of the returned dictionary for all attribution details
NSLog(@"Attribution Dictionary: %@", attributionDetails); 
}];
}

The following sample code shows the dictionary structure you can expect to receive when you call requestAttributionDetails(_:):

{ 
"Version3.1" = { 
"iad-attribution" = true; 
"iad-org-name" = "org name";
"iad-org-id" = “555555”;
"iad-campaign-id" = "12345678"; 
"iad-campaign-name" = "campaign name"; 
"iad-purchase-date" = "2020-01-04T17:18:07Z" 
"iad-conversion-date" = "2020-01-04T17:18:07Z"; 
"iad-conversion-type" = "Download"; 
"iad-click-date" = "2020-01-04T17:17:00Z"; 
"iad-adgroup-id" = "12345678"; 
"iad-adgroup-name" = "adgroup name"; 
"iad-country-or-region" = "US"; 
"iad-keyword" = "keyword";
"iad-keyword-id" = 12345678";
"iad-keyword-matchtype" = "Broad";
"iad-creativeset-id" = "12345678";
"iad-creativeset-name" = "Creative Set name";
}

Download Attribution Data

When your app has retrieved the attribution dictionary, you can upload the attribution data to your server using the method of your choice.

The following list shows the data dictionary keys and data types the Apple Search Ads Attribution API returns.

iad-attribution

Boolean. True if the user clicked an Apple Search Ads impression up to 30 days before app download.

iad-org-name

String. The organization that owns the campaign the corresponding ad was part of.

iad-org-id

Integer. The ID of the organization that owns the campaign the corresponding ad was part of.

iad-campaign-id

Integer. The ID of the campaign the corresponding ad was part of.

iad-campaign-name

String. The name of the campaign the corresponding ad was part of.

iad-click-date

Date/time string. The date and time when the user clicked a corresponding ad.

iad-purchase-date

Date/time string. The date and time when the user first downloaded your app. When the value of iad-conversion-type is redownload, this string represents the original purchase date. The purchase may or may not have been associated with an Apple Search Ad.

iad-conversion-date

Date/time string. The date and time when the user downloaded your app by clicking an Apple Search Ad.

iad-conversion-type

String. The type of conversion will either be a new download or a redownload. A redownload is a download of an app by users who have previously installed your app.

iad-adgroup-id

Integer. The ID of the ad group the corresponding ad was part of.

iad-adgroup-name

String. The name of the ad group the corresponding ad was part of.

iad-country-or-region

String. The country or region associated with the campaign that drove the install.

iad-keyword

String. The keyword that drove the ad impression that led to the corresponding ad click.

iad-keyword-id

String. The ID of the keyword that drove the ad impression.

iad-keyword-matchtype

String. The match type of the keyword that drove the ad impression. Values are Broad, Exact, or Search Match.

iad-creativeset-id

Integer. The ID of the Creative Set the corresponding ad was part of.

iad-creativeset-name

String. The name of the Creative Set the corresponding ad was part of.

See Handling Errors for possible errors with data that has been returned.

Report Attribution Data

Attribution data reporting helps you track performance of your campaigns. The following conditions apply to attribution data.

  • All actions must occur on the same device.

  • Attribution only applies to users running iOS 10 or later, and who have downloaded the app within the previous 30 days.

  • Apple Search Ads reports a download as it happens, and up to 30 days later.

  • A download or redownload must occur from an App Store listing or an Apple Search Ads impression.

If you integrate your data reporting strategy with a Mobile Measurement Provider (MMP), note the differences with MMP methodology when compared to Apple Search Ads:

  • Apple Search Ads uses a 30-day attribution window. Third-party attribution may only allow an attribution window of 7 to 28 days.

  • "App open latency" may be one of the reasons for a difference in the total install count. App open latency is the delay between an install and first launch. MMPs typically report an install when the app is opened for the first time. Apple Search Ads reports when a download is completed.

  • For users with Limit Ad Tracking enabled, a device IDFA (ID for advertisers) does not populate. This may be sent as a string of zeros to attribution partners. In these cases, installs cannot be attributed or may be attributed as organic.

  • Third parties may not count redownloads as installs. Third parties do not have visibility to know an app has been previously removed from a device. They may attribute a redownload as another app open latency or user engagement.

See Also

Apple Search Ads Attribution API

class ADClient

Ad information specific to an app.