Implement Apple AdServices Framework: Zero-SDK Attribution
Accurately attributing installs to Apple Search Ads (ASA) campaigns often means integrating heavyweight third-party Mobile Measurement Partner (MMP) SDKs. These SDKs add build time, increase app size, and introduce external dependencies, which might be overkill for indie developers aiming for a lean tech stack.
You can implement the Apple AdServices Framework for Apple Search Ads attribution directly in Swift using AAAttribution.attributionToken(). This approach lets you track ASA installs without additional third-party SDKs, keeping your app nimble and your privacy posture strong. This post outlines how to fetch this token and use it to measure your ASA campaign performance.
Why Apple AdServices is Essential for Indie Developers
Apple Search Ads allows you to promote your app directly on the App Store search results page. When users search for keywords related to your app, your ad can appear at the top, leading to highly qualified installs. Knowing which installs came from which ad campaigns is crucial for optimizing your ad spend.
The AdServices framework, introduced with iOS 14.3, provides a privacy-preserving way to attribute app installs to Apple Search Ads. It offers aggregated attribution data to help you understand campaign performance without compromising user privacy. For solo developers, this allows direct measurement of marketing efforts, avoiding the cost or complexity of external solutions.
The core mechanism is the attribution token, a cryptographically signed string that your app retrieves and sends to your server. Your server then sends this token to Apple's AdServices API for validation, which returns aggregated campaign details. This process works independently of the App Tracking Transparency (ATT) framework, meaning explicit user consent is not required to fetch this token.
Setting Up Your Project for AdServices
To retrieve an attribution token, configure your Xcode project to use the AdServices framework:
- Open your Xcode project.
- In the Project Navigator, select your project, then select your app target.
- Navigate to the "General" tab.
- Scroll down to the "Frameworks, Libraries, and Embedded Content" section.
- Click the
+button to add a new framework. - Search for
AdServices.frameworkand select it. Ensure "Embed & Sign" is chosen for the embedding option.
Adding the framework automatically grants your app the necessary entitlement: com.apple.developer.adservices.attributetoken. You do not need to manually add this entitlement in your .entitlements file; Xcode handles it when you link the framework. Your app must target iOS 14.3 or later to use the AdServices framework.
While AdServices.framework does not require specific entries in your app's PrivacyInfo.xcprivacy file for its core attribution token functionality, Apple's guidelines specify its use is solely for ASA attribution and does not collect identifiable user data.
Retrieving the Attribution Token in Swift
The AAAttribution.attributionToken() method is key for zero-SDK attribution. This asynchronous function returns an optional String containing the attribution token. Call this method early in your app's lifecycle, typically on the first launch, to capture attribution data promptly.
import AdServices
import Foundation // For URLSession, etc.
func fetchAdServicesAttributionToken() async -> String? {
if #available(iOS 14.3, *) {
do {
let token = try await AAAttribution.attributionToken()
print("Successfully fetched AdServices Attribution Token: \(token)")
return token
} catch {
print("Error fetching AdServices attribution token: \(error.localizedDescription)")
// Handle specific errors, e.g., if attribution is not available
return nil
}
} else {
print("AdServices framework requires iOS 14.3 or later. Current iOS version is too old.")
return nil
}
}
You can call this function from your AppDelegate or SceneDelegate when your app starts up. For instance, you might call it as shown:
// In your AppDelegate or SceneDelegate:
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Task {
if let token = await fetchAdServicesAttributionToken() {
// Send this token to your backend for validation with Apple's AdServices API
sendTokenToServer(token)
}
}
return true
}
func sendTokenToServer(_ token: String) {
// Implement your network request here to send the token to your server
// Example:
guard let url = URL(string: "https://your-backend.com/api/v1/adservices-attribution") else { return }
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
let body: [String: String] = ["attribution_token": token]
request.httpBody = try? JSONEncoder().encode(body)
URLSession.shared.dataTask(with: request) { data, response, error in
if let error = error {
print("Error sending token to server: \(error.localizedDescription)")
return
}
if let httpResponse = response as? HTTPURLResponse, httpResponse.statusCode == 200 {
print("Attribution token sent to server successfully.")
} else {
print("Server responded with error or unexpected status code.")
}
}.resume()
}
For example, if you ship a habit tracker app and want to know if new users installed it after seeing your ASA campaign for "daily planner" keywords, you would call fetchAdServicesAttributionToken() on app launch. If a token is returned, send it to your server. Your server then performs the actual attribution lookup with Apple, and if successful, records that this install originated from an ASA campaign, potentially with specific campaign and ad group IDs.
Sending the Attribution Token to Your Server
The AAAttribution.attributionToken() value is a cryptographically signed payload that your server must verify with Apple's AdServices API. This server-side verification retrieves the final attribution data.
Your backend server should perform the following steps:
- Receive the Token: Your app sends the attribution token (the
Stringvalue) to a dedicated endpoint on your server. - Make a Request to Apple: Your server then makes a POST request to Apple's AdServices API endpoint:
https://api-adservices.apple.com/api/v1/attribution. The request body must contain the received attribution token. - Process Apple's Response: Apple's API will respond with a JSON payload containing the attribution details. This data is aggregated and privacy-preserving. It includes information like
campaignId,adGroupId,keywordId, andcreativeId. - Store and Analyze: Your server can then store this attribution data alongside your install records. Use this to understand which Apple Search Ads campaigns are driving installs and measure your return on ad spend (ROI).
This data is designed for aggregate reporting; it will not include individual user identifiers or highly granular personal data. This aligns with Apple's privacy principles, allowing campaign optimization while respecting user privacy. For more detailed server-side implementation specifics, refer to Apple's AdServices API documentation.
A Checklist for AdServices Implementation
Follow this checklist for a smooth Apple AdServices implementation:
- Deployment Target: Verify your app's deployment target is set to iOS 14.3 or later in your Xcode project settings.
- Framework Inclusion: Confirm that
AdServices.frameworkis added to your target's "Frameworks, Libraries, and Embedded Content" section in Xcode and set to "Embed & Sign". - Swift Code for Token Retrieval: Implement an asynchronous function similar to
fetchAdServicesAttributionToken()in your app. Ensure it includes error handling for cases where a token cannot be retrieved. - Token Transmission: Set up a reliable mechanism to send the retrieved attribution token from your app to your backend server, typically via a secure HTTP POST request.
- Backend Endpoint: Develop a server-side endpoint that can receive the attribution token from your app.
- Apple AdServices API Integration: Your backend must be capable of making a POST request to
https://api-adservices.apple.com/api/v1/attributionwith the received token and parsing the JSON response. - Data Storage: Configure your database to store the attribution data (campaign ID, ad group ID, etc.) returned by Apple's API.
- Testing Strategy: Plan to test your implementation with an actual Apple Search Ad campaign. Even a small, low-budget campaign can provide real data to verify your setup.
- Privacy Considerations: Be aware that while
AAAttribution.attributionToken()works independently of ATT, if you also use ATT for other purposes, ensure your privacy policy accurately reflects all data practices.
FAQ
Do I need user consent via ATT for AdServices to work?
No. The AAAttribution.attributionToken() function retrieves an attribution token specifically for Apple Search Ads and operates independently of the App Tracking Transparency (ATT) framework. You do not need to request tracking authorization from the user for this specific functionality.
What data does Apple AdServices provide?
Apple AdServices provides aggregated campaign data. This includes details like campaignId, adGroupId, keyword (the search term that triggered the ad), creativeType, and other high-level campaign metadata. It does not provide user-specific or device-specific identifiers.
Can I use AdServices with third-party analytics?
Yes, you can. While the core benefit of this approach is avoiding a *third-party SDK* for attribution, you can still pass the aggregated attribution data (like campaign IDs) that your server receives from Apple's API to your chosen analytics platform. This allows you to correlate ASA performance with other app metrics.
Is there a rate limit for attributionToken()?
There is no publicly documented rate limit for calling AAAttribution.attributionToken() from the client app. However, Apple's AdServices API endpoint (https://api-adservices.apple.com/api/v1/attribution), which your *server* calls, does have rate limits to prevent abuse. Design your server-side integration to handle these limits gracefully.
What if attributionToken() returns nil or throws an error?
If attributionToken() returns nil or throws an error, it often means that no attribution data is available (e.g., the install was organic, or the ad click occurred outside the attribution window). Your app should handle these cases gracefully, perhaps by logging the error but continuing without attribution data for that specific install.
Your Next Step: Implement and Measure
Implementing Apple's AdServices framework directly in Swift provides precise control over your attribution pipeline for Apple Search Ads, without external SDK overhead. Integrate AAAttribution.attributionToken() into your app. After implementation, use tools like the ASO Keyword Analyzer to refine ad campaign keywords, or create compelling App Store screenshots that convert attributed installs into engaged users.
Make your App Store screenshots free
LaunchShots is a free, in-browser screenshot maker. No signup, no watermark.
Open the app →
Comments (0)