Apple Search Ads & RevenueCat Integration

Collect and view Apple Search Ads attribution in RevenueCat using AdServices

Ask AI

Copied as markdown!

With our Apple Search Ads integration you can:

• Continue to follow your campaign's install base for months to understand the long-tail revenue generated from subscriptions, even without an app open.
• Filter and segment RevenueCat charts by Apple Search Ads campaigns or ad groups.

Collecting Apple Search Ads data is a two part process:

1. You must collect the user's attribution token and send it to RevenueCat
2. With this token, RevenueCat will request attribution data from Apple directly within a 24 hour period

Once attribution data is collected from Apple, it will be available via Charts and other integrations.

1. Configure Integration

❗️Basic vs. Advanced

Apple Search Ads offer two products, Search Ads Basic and Search Ads Advanced. The RevenueCat Apple Search Ads integration supports both Basic and Advanced. However, Advanced will require more configuration than Basic.

Basic

• Navigate to your project in the RevenueCat dashboard and choose Apple Ads Services from the Integrations menu.
• Click on Add Apple Search Ads integration to add the integration.

⚠️Basic integration is not yet complete

Please advance to step 2 to send the attribution token to RevenueCat. Without this step, RevenueCat will not be able to collect Apple Search Ads data.

Advanced

If you already have an Advanced integration set up using the legacy method (clientId, teamId, and keyId), your existing setup will continue working. We recommend anyway migrating to the new approach to align with current best practices.

• Navigate to your project in the RevenueCat dashboard and choose Apple Ads Services from the Integrations menu.
• Click on Add Apple Search Ads integration to add the integration.
• Click Sign in with Apple button in the Advanced integration section.
• Sign in to Apple Search Ads and authorize RevenueCat access.

📘Apple Search Ads API User permissions

On Apple’s permission screen, these options are compatible:

• Read Only: ✅ Recommended. This is sufficient for RevenueCat and provides a reliable setup.
• Read and Write: ✅ Also compatible, but grants more access than RevenueCat needs.
• Limited Access: ⚠️ Compatible only if access includes all campaign groups RevenueCat needs. Otherwise, you may see partial data or authorization errors that can cause unexpected integration behavior.

The Apple user must also have one of these API roles: API Account Manager, API Account Read Only, or Limited Access API Read & Write / API Read Only.

More info about creating these users can be found here.

Please make sure you do not use an incognito window when creating a new Apple Account for the API user, as this has caused issues for other developers.

• Return to RevenueCat and confirm the integration is connected.

If access is revoked from Apple, you must reconnect in RevenueCat to resume data collection.

2. Send attribution token to RevenueCat

📘Compatibility

Using AdServices to collect Apple Search Ads data requires iOS 14.3+, and is not supported on earlier versions of iOS. If you need to continue collecting Apple Search Ads data for older versions of iOS, follow our legacy Apple Search Ads instructions.

Apple Search Ads provides two different types of attribution data, one a Standard view and one a Detailed view. Attribution fields vary between the two types of data, which may affect downstream integrations, and will require a different client-side implementation.

	Standard	Detailed
App Tracking Consent Required	No	Yes
attribution	✅	✅
campaignId	✅	✅
conversionType	✅	✅
clickDate	❌	✅
adGroupId	✅	✅
countryOrRegion	✅	✅
keywordId	✅	✅
adId	✅	✅
claimType	✅	✅
impressionDate	❌	✅

Note that this is the same data that is sent to other downstream integrations that receive Apple Search Ads data (like SplitMetrics Acquire). If you need fields that are unavailable in the Standard data, use Detailed instead.

Standard

The standard attribution data collection does not require user consent and can be enabled by calling Purchases.shared.attribution.enableAdServicesAttributionTokenCollection() after calling configure:

Swift

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    Purchases.configure(withAPIKey: "public_sdk_key", appUserID: "my_app_user_id")
    Purchases.shared.attribution.enableAdServicesAttributionTokenCollection()

    return true
}

Obj-C

- (BOOL)application:(UIApplication *)application 
  didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  
  RCPurchases *purchases = [RCPurchases configureWithAPIKey:@"public_sdk_key" appUserID:@"my_app_user_id"];
  [purchases.attribution enableAdServicesAttributionTokenCollection];

}

Flutter

// ...
await Purchases.configure(PurchasesConfiguration(<public_api_key>));
// ...
await Purchases.enableAdServicesAttributionTokenCollection();

React Native

// ...
Purchases.configure({apiKey: <public_api_key>});
// ...
Purchases.enableAdServicesAttributionTokenCollection();

Cordova

// ...
Purchases.configureWith({apiKey: <public_api_key>});
// ...
Purchases.enableAdServicesAttributionTokenCollection();

That's it! The Purchases SDK will collect the attribution token and send it to RevenueCat in the background.

Detailed

To collect Detailed attribution data, you'll need to first request consent from your users by using the App Tracking Transparency framework.

If the user rejects tracking, the Standard attribution data can still be collected.

To request consent from a user, implement the requestTrackingAuthorization method before enabling automatic collection:

Swift

import AdServices

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

     Purchases.configure(withAPIKey: "public_sdk_key", appUserID: "my_app_user_id")

     if ATTrackingManager.trackingAuthorizationStatus != .notDetermined {
     // The user has previously seen a tracking request, so enable automatic collection
     // before configuring in order to to collect whichever token is available
     Purchases.shared.attribution.enableAdServicesAttributionTokenCollection()
    }

    return true
}

// Later in your app's lifecycle, ask consent for tracking
if ATTrackingManager.trackingAuthorizationStatus == .notDetermined {
    ATTrackingManager.requestTrackingAuthorization { _ in
        Purchases.shared.attribution.enableAdServicesAttributionTokenCollection()
    }
}

After automatic collection is enabled, Purchases will sync the attribution token with the RevenueCat backend. Please note that if you enable automatic collection before requesting authorization, the attribution token will only be valid for Standard and not Detailed attribution data.

3. View attribution data in RevenueCat

After the Purchases SDK has collected attribution for some users, you'll be able to use Charts to analyze your Apple Search Ads data.

View charts

Apple Search Ad attribution is available as segments and filters in the vast majority of applicable charts that measure subscription, trial, revenue, lifetime value, and conversion data.

The charts without support for Apple Search Ads attribution are:

• Subscription Retention
• Customer Center Survey Responses
• Play Store Cancel Reasons
• App Store Refund Requests

Available filters/segments

We support the following filters and segments for Apple Search Ads:

1. Attribution source: Breakdown your measures by Apple Search Ads or Organic.
2. Apple search ads campaign: Breakdown your measures by the campaign they derived from.
3. Apple search ads group: Breakdown your measures by the ad group they derived from.
4. Apple search ads keyword: Breakdown your measures by the keyword they derived from.
5. Apple search ads claim type: Breakdown your measures by the claim type of Click for click-through attribution, or Impression for view-through attribution.

Filter chart to compare individual campaigns, ad groups, or keywords

Select and deselect rows to compare individual campaigns, ad sets, or keywords

The value of Unspecified is used to group transactions that are attributed to an Apple Search Ads ad, but do not have a specified Campaign Name, Ad Group Name, or Keyword.

This commonly occurs in two scenarios:

• The ad was delivered through an Apple Search Ads Basic account, where these fields are not provided by Apple.
• The attribution originates from a debug or TestFlight environment, where Apple may return placeholder or empty Apple Search Ads attribution data.

The value of Organic is used to group transactions that are not attributed to an Apple Search Ads campaign. This means it was an organic install or users with limit ad tracking enabled. To exclude organic installs from your charts, you can filter by Attribution source and select Apple Search Ads.

⚠️Allow up to 7 days to gather attribution data

If your campaigns are new or you recently set up the Apple Search Ads integration, allow some time for RevenueCat to collect attribution and purchase data.