ο»Ώ

The Apple Search Ads (AdServices) integration is available on the [Pro](πŸ”—ο»Ώ) plan, Enterprise plan, and legacy Grow plan and is supported in iOS SDK version 4.10.0 and up

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: first, you must collect the user's attribution token and send it to RevenueCat, then 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 integrations 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.

## Advanced

  • 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.

  • Go to **Account Settings** > **API** in your Search Ads dashboard, and paste your public key in the **Client Credentials** section in settings of your **API User**.

Saving your public key may require Safari

Apple Search Ads may reject the public key with an 'invalid' error message if you're using a browser other than Safari. If you get this error, try switching to Safari to save the key.

Apple Search Ads API User

RevenueCat uses the Campaign Management API to access the campaign data from Apple Search Ads. This API requires access through a separate Apple ID that with one of the following roles: **API Account Manager**, **API Account Read Only**, or **Limited Access API Read** & **Write or 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 ID for the API user as we have seen it cause difficulties for other developers.

2012
ο»Ώ

ο»Ώ

If you're having trouble finding the screen where you can add upload your public key to Client Credentials, ensure that you're logged in as the client Apple ID, and not your primary Apple ID.

  • Then, copy the provided `clientId`, `teamId` and `keyId` from the Search Ads page to your RevenueCat Dashboard.

  • Click the 'Save' button in the top right corner.

ο»Ώ

# 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.

Column Titleο»Ώ
StandardDetailed
App Tracking Consent RequiredNoYes
`attribution`βœ…βœ…
`campaignId`βœ…βœ…
`conversionType`βœ…βœ…
`clickDate`βŒβœ…
`adGroupId`βœ…βœ…
`countryOrRegion`βœ…βœ…
`keywordId`βœ…βœ…
`adId`βœ…βœ…

ο»Ώ

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`:

ο»Ώ

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:

ο»Ώ

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 segment and view charts for those conversions.

## Choose conversion level

In the 'Select Segment' dropdown choose _Apple search ads group_ or _Apple search ads campaign_ from the Segment section.

ο»Ώ

## View charts

Apple Search Ad attribution is available as segments and filters in the following charts:

  • Active Subscriptions

  • Churn

  • Refund Rate

  • Annual Recurring Revenue (ARR)

  • Monthly Recurring Revenue (MRR)

  • Revenue

  • Active Trials

ο»Ώ

## Filter chart to compare individual campaigns or ad groups

Select and deselect rows to compare individual campaigns or ad sets

ο»Ώ

ο»Ώ

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 or Ad Group Name. This is almost always because the ad has been delivered through an Apple Search Ads Basic account, where campaign names and ad group names are not specified.

ο»Ώ

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.

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.