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:
| Field | Meaning |
|---|
attribution | true when an Apple Ads campaign drove the install |
orgId | your Apple Ads organization ID |
campaignId | the campaign that drove the install |
adGroupId | the ad group inside that campaign |
keywordId | the keyword that matched |
adId | the ad that was shown |
conversionType | Download, Redownload or PreOrder |
countryOrRegion | two-letter country or region code, for example US |
claimType | how the attribution was claimed: Click for a tap on the ad, Impression for a view without a tap |
supplyPlacement | the App Store placement that showed the ad |
impressionDate | the 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.