Identify meaningful metrics by retrieving the attribution dictionary.
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.
From Xcode, go to your target view and select General.
Scroll down to the Linked Frameworks and Libraries section and click the plus (+) icon.
In the dropdown menu, choose iAd.framework, and then click Add.
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
request 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.
The following sample code shows the dictionary structure you can expect to receive when you call
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.
Trueif the user clicked an Apple Search Ads impression up to 30 days before app download.
String. The organization that owns the campaign the corresponding ad was part of.
Integer. The ID of the organization that owns the campaign the corresponding ad was part of.
Integer. The ID of the campaign the corresponding ad was part of.
String. The name of the campaign the corresponding ad was part of.
Date/time string. The date and time when the user clicked a corresponding ad.
Date/time string. The date and time when the user first downloaded your app. When the value of
iad-conversion-typeis redownload, this string represents the original purchase date. The purchase may or may not have been associated with an Apple Search Ad.
Date/time string. The date and time when the user downloaded your app by clicking an Apple Search Ad.
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.
Integer. The ID of the ad group the corresponding ad was part of.
String. The name of the ad group the corresponding ad was part of.
String. The country or region associated with the campaign that drove the install.
String. The keyword that drove the ad impression that led to the corresponding ad click.
String. The ID of the keyword that drove the ad impression.
String. The match type of the keyword that drove the ad impression. Values are Broad, Exact, or Search Match.
Integer. The ID of the Creative Set the corresponding ad was part of.
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.