How to use the Attribution API for tracking installs via Apple Search Ads

Apple Search Ads is one of the many new introductions to the App Store for 2016.  The new search ads allow developers and marketers to promote their iOS Apps at the top of App Store search results by bidding on search keywords.

You bid on how much you are willing to pay for a user to tap on your ad.  For the most part you want to keep the average cost per acquisition (Avg CPA) below the lifetime value of a user.  Lloyd Melnick blog defines LTV as consisting of three components: monetization, retention and virality.  If you have a premium or paid up front app the monetization calculation is fairly straight forward, as it is simply the price of the app minus Apple’s 30% cut and any applicable taxes.

However, if your app uses in-app purchases, subscriptions, advertisements, e-commerce, or some other method of monetization then figuring out the monetization component of LTV is trickier.  The average CPA or LTV may vary per keyword.  Using the Attribution API we can calculate the average LTV for users acquired via Apple Search Ads at the keyword level.

To use the Attribution API you will need to implement the requestAttributionDetails method to retrieve the dictionary containing the attribution details.  In Objective-C the method looks like

[ADClient sharedClient] requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error)

and in Swift 3 it is

ADClient.shared().requestAttributionDetails

For more sample code refer to apples online documentation here or the full Search Ads Attribution API documentation here as a pdf.  You can also watch the WWDC video here for a full introduction to Search Ads.

When requesting attribution data from within the simulator, sample data returned differs from both the video and documentation examples.  The extra fields include a creative id and name as well as a line item id and name.  Below is the full sample dictionary returned.

    "iad-adgroup-id" = 1234567890;
    "iad-adgroup-name" = AdGroupName;
    "iad-attribution" = true;
    "iad-campaign-id" = 1234567890;
    "iad-campaign-name" = CampaignName;
    "iad-click-date" = "2016-12-05T17:31:40Z";
    "iad-conversion-date" = "2016-12-05T17:31:40Z";
    "iad-creative-id" = 1234567890;
    "iad-creative-name" = CreativeName;
    "iad-keyword" = Keyword;
    "iad-lineitem-id" = 1234567890;
    "iad-lineitem-name" = LineName;
    "iad-org-name" = OrgName;
}]

In production environments the iad-creative-id and iad-creative-name are omitted.

Update: Sep 28, 2017.  When requesting attribution data from an iOS 11 simulator it no longer returns sample data but rather an error with the following contents: Error Domain=ADClientErrorDomain Code=0 NSLocalizedDescription="Unable to retrieve attribution details". However, requesting data from your iOS 10 or iOS 11 test device still returns the sample dictionary as long as you have Limit Ad Tracking turned off.

To get the cost per tap or the cost per acquisition you’ll need to query the Search Ads API from your server.

Kitemetrics is a service that will automatically perform keyword attribution and calculate the average Revenue Per User generated via In-App Purchases.  Simply add the Kitemetrics client SDK via CocoaPods or as a framework.  It will make the requestAttributionDetails call, capture completed in-app purchases, and log other custom events you choose.

Visit kitemetrics.com to learn more and sign up for a free account.