ActivationPal

AdServices Framework: Apple Ads Attribution

AdServices is Apple's framework that gives your app an attribution token, which Apple's attribution API resolves into the Apple Ads campaign behind the install. No App Tracking Transparency prompt is needed.

What the AdServices framework is

AdServices runs on iOS 14.3+ and macOS 11.1+ and attributes installs that came from Apple Ads placements on the App Store: search results, the Search tab, the Today tab and product pages.

The app never receives campaign details directly. It receives an opaque token and exchanges it for the attribution data in a second step, so other SDKs in the app have nothing to read but the token.

Get the attribution token with AAAttribution.attributionToken()

Import AdServices and ask for the token once the app has launched:

import AdServices

if #available(iOS 14.3, *) {
    let token = try? AAAttribution.attributionToken()
}

The call can throw, so try? returns nil on failure. Treat nil as "try again later", not as "organic install". Call it at first launch and keep the token until you have sent it on.

The ActivationPal Swift SDK captures this token at first open, with no prompt.

Post the token to Apple's attribution API

Send the token as the plain-text body of a POST to https://api-adservices.apple.com/api/v1/ with the content type text/plain. The endpoint needs no authentication.

func resolveAttribution() async throws -> Data? {
    guard let token = try? AAAttribution.attributionToken() else { return nil }

    var request = URLRequest(url: URL(string: "https://api-adservices.apple.com/api/v1/")!)
    request.httpMethod = "POST"
    request.setValue("text/plain", forHTTPHeaderField: "Content-Type")
    request.httpBody = Data(token.utf8)

    let (data, _) = try await URLSession.shared.data(for: request)
    return data
}

The same request works from a server, which is useful when you want the lookup off the device.

What the AdServices API returns

The response is JSON with these fields:

FieldMeaning
attributiontrue when an Apple Ads campaign drove the install
orgIdyour Apple Ads organization ID
campaignIdthe campaign that drove the install
adGroupIdthe ad group inside that campaign
keywordIdthe keyword that matched
adIdthe ad that was shown
conversionTypeDownload, Redownload or PreOrder
countryOrRegiontwo-letter country or region code, for example US
claimTypehow the attribution was claimed: Click for a tap on the ad, Impression for a view without a tap
supplyPlacementthe App Store placement that showed the ad
impressionDatethe date of the ad impression, returned for view-through attribution

Every identifier is a number, not a name. Names come from the Apple Ads Platform API, which requires OAuth 2.0. A clickDate field is added only when the user allowed ATT.

Timing and retries

A token minted a moment ago can get a 404 from the attribution API before its record is available. Wait and ask again rather than giving up on the install.

ActivationPal resolves tokens this way: up to 3 attempts, 5 seconds apart.

Only the device can mint a token, so capture it at first open and queue it. The lookup can then happen later, or on a server.

Capture the token with the ActivationPal SDK

You can skip the plumbing above. The Swift SDK captures the AdServices token at first open and sends it as an asa_token event. If the first attempt fails, it tries again on later launches until the token is safely in its event queue. The React Native and Flutter packages do the same through their iOS bridges, with nothing extra to add. Setup is in the Quickstart.

ActivationPal then resolves the token against Apple's API on its server and records an install_attribution event. In the Acquisition card you see Apple Ads installs next to organic installs, with a per-campaign split. Connect your Apple Ads API as described in the Apple Ads docs and the same card adds spend, CPI and impressions. No tracking prompt is shown to the user.

AdServices covers Apple Ads only; what a mobile measurement partner does covers other channels. With spend connected, user acquisition cost shows what an Apple Ads install cost you.

AdServices vs SKAdNetwork

The two answer different questions. AdServices attributes an install to an Apple Ads campaign by looking up a token. SKAdNetwork is Apple's separate privacy-preserving system for install postbacks, used by ad networks in general rather than only Apple Ads.

Frequently asked questions

Why does the response show no attribution for an install?

The response is attribution: false when the install did not come from an Apple Ads campaign, as with an organic install. Apple also returns attribution: false when the ad group uses age or gender settings. ActivationPal counts those installs as organic in the Acquisition split.

Do I need the Apple Ads API to use AdServices?

No. The attribution endpoint needs no authentication and gives you campaign, ad group and keyword IDs. You need the Apple Ads API only to turn IDs into names or to pull spend, CPI and impressions, which ActivationPal reads once you connect it.

Does AdServices work on Android?

No. Apple Ads attribution applies to the iOS SDKs. The Android analytics SDK works without it, and an app that ships on both platforms still gets Apple Ads attribution for its iPhone installs.