Setting Up Apple Search Ads Attribution
Retrieve the attribution dictionary.
Overview
The attribution dictionary contains attribution data that the system retrieves from user interaction with ads originating from Apple Search Ads campaigns.
[Image]
To retrieve the attribution dictionary, use the following process in sequence.
Retrieve the Attribution Dictionary
See the ADClient/requestAttributionDetails(_:) method for the conditions to retrieve the dictionary that contains the attribution object. Next, check for Apple Search Ads attribution, such as at app 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 example shows the dictionary structure you receive when you call ADClient/requestAttributionDetails(_:):
{
"Version3.1" = {
"iad-attribution" = true;
"iad-org-name" = "org name";
"iad-org-id" = "40669820";
"iad-campaign-id" = "542370539";
"iad-campaign-name" = "campaign name";
"iad-purchase-date" = "2020-08-04T17:18:07Z"
"iad-conversion-date" = "2020-08-04T17:18:07Z";
"iad-conversion-type" = "newdownload";
"iad-click-date" = "2020-08-04T17:17:00Z";
"iad-adgroup-id" = "542317095";
"iad-adgroup-name" = "adgroup name";
"iad-country-or-region" = "US";
"iad-keyword" = "keyword";
"iad-keyword-id" = "87675432";
"iad-keyword-matchtype" = "Broad";
"iad-ad-id" = "542317136";
}Download Attribution Data
After your app retrieves the attribution dictionary, upload the attribution data to your server using the method of your choice. Next, check for Apple Search Ads attribution. Store the data locally, so you don’t need to repeat the method call.
The following list contains the data dictionary keys and data types the iAd framework returns:
iad-attributionBoolean.
Trueif the user clicks an Apple Search Ads impression up to 30 days before app download or redownload.iad-org-nameString. The organization that owns the campaign that the corresponding ad belongs to.
iad-org-idInteger. The
Idof the organization that owns the campaign that the corresponding ad belongs to.iad-campaign-idInteger. The
Idof the campaign that the corresponding ad belongs to.iad-campaign-nameString. The name of the campaign that the corresponding ad belongs to.
iad-click-dateDate/Time string. The date and time when the user clicks a corresponding ad.
iad-purchase-dateDate/Time string. The date and time when the user first downloads your app. When the value of
iad-conversion-typeisredownload, this string represents the original purchase date. The purchase may or may not be associated with an Apple Search Ad.iad-conversion-dateDate/Time string. The date and time when the user downloads or redownloads your app by clicking an Apple Search Ad.
iad-conversion-typeString. The type of conversion is either a
newdownloador aredownload. Aredownloadis a download of an app by users who have previously installed your app.iad-adgroup-idInteger. The
Idof the ad group that the corresponding ad belongs to.iad-adgroup-nameString. The name of the ad group that the corresponding ad belongs to. See Ad Groups for more information.
iad-country-or-regionString. The country or region associated with the campaign that results in an installation.
iad-keywordString. The keyword for the ad impression that led to the corresponding ad click.
iad-keyword-idString. The
Idof the keyword for the ad impression.iad-keyword-matchtypeString. The match type of the keyword for the ad impression. Values are
Broad,Exact, or search match. See Ad Groups for more information.iad-ad-idInteger. The
Idof the ad that the corresponding ad belongs to.
Report Attribution Data
Attribution data reporting helps you track performance of your campaigns. The following conditions apply to attribution data:
All actions need to occur on the same device.
Attribution only applies to users running iOS 10 or later, and who have downloaded or redownloaded the app within the previous 30 days.
Apple Search Ads reports a download or a redownload as it happens, and up to 30 days later.
A download or a redownload needs to 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 installation count. App open latency is the delay between an installation and first launch. MMPs typically report an installation when the app opens for the first time. Apple Search Ads reports an installation when a download or redownload is complete.
Third parties may not count redownloads as installations. Third parties don’t have visibility to know whether an app has been previously removed from a device. They may attribute a redownload as another app open latency or user engagement.