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" = "org launch"; 
"iad-purchase-date" = "2019-10-14T17:18:07Z" 
"iad-conversion-date" = "2019-10-14T17:18:07Z"; 
"iad-conversion-type" = "Download"; 
"iad-click-date" = "2019-10-14T17:17:00Z"; 
"iad-adgroup-id" = "12345678"; 
"iad-adgroup-name" = "org launch group"; 
"iad-country-or-region" = "US"; 
"iad-keyword" = "keyword";
"iad-keyword-id" = 12345678";
"iad-keyword-matchtype" = "Broad";
"iad-creativeset-id" = "12345678";
"iad-creativeset-name" = "Nature Images";
}

Attribution data reporting requires the following:

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

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

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.

See Also

Apple Search Ads Attribution API

class ADClient

Ad information specific to an app.