What this setup connects
Apple Ads can show which campaigns, ad groups, and keywords spent money and produced attributed downloads. RevenueCat can show trials, subscriptions, renewals, cancellations, and long-term revenue. Connecting them lets you follow the users acquired through paid App Store search beyond the install.
The connection has two separate parts: authorize RevenueCat to read the Apple Ads account, then make the app send an AdServices attribution token to RevenueCat.
Completing only the dashboard connection is not enough. Completing only the code change is not enough. You need both before campaign and keyword attribution can appear beside RevenueCat revenue.
RevenueCat and many developers still use the name Apple Search Ads or ASA. Apple now calls the product Apple Ads. This guide uses “Apple Search Ads” where that is the label shown inside RevenueCat.
Before you start
You need:
- an iOS app using the RevenueCat Purchases SDK;
- a RevenueCat project connected to that app;
- an Apple Search Ads Advanced account with the relevant campaigns;
- an Apple Ads user who is an Account Admin or Campaign Group Manager;
- a new app release containing the attribution call described below; and
- production traffic and purchases after that release.
RevenueCat documents AdServices collection for iOS 14.3 and later. Do not assume historical installs and purchases will be backfilled when you enable the integration. Plan the first validation around new production acquisition after the updated app is released.
Step 1: Connect Apple Search Ads Advanced in RevenueCat
- Open the correct project in RevenueCat.
- Go to Integrations and choose Apple Search Ads.
- Select Add Apple Search Ads integration.
- In the Advanced section, choose Sign in with Apple.
- Sign in to the Apple Ads account that owns the campaigns.
- Choose the account and grant RevenueCat access.
- Return to RevenueCat and confirm that the integration shows as connected.
RevenueCat recommends Read Only access because it is sufficient for attribution. Read and Write also works but grants more access than RevenueCat needs. If you use Limited Access, include every campaign group whose attribution you expect RevenueCat to resolve. Otherwise the data can be partial.
The person authorizing the connection must be an Apple Ads Account Admin or Campaign Group Manager. Apple’s Campaign Management API guide explains how third-party access is granted and later reviewed or revoked.
Match the account type correctly. If you run Apple Search Ads Advanced but configure Basic in RevenueCat, the additional campaign, ad group, and keyword detail will not be available.
Step 2: Enable AdServices attribution in Swift
Add the attribution call immediately after configuring RevenueCat at app startup:
import RevenueCat
Purchases.configure(withAPIKey: "public_sdk_key")
Purchases.shared.attribution.enableAdServicesAttributionTokenCollection()The order matters: configure Purchases first, then enable AdServices attribution token collection. Place the two calls in the startup path your app already uses, such as the app delegate or SwiftUI app initializer.
RevenueCat’s SDK requests Apple’s AdServices attribution token and sends it to RevenueCat. RevenueCat then requests the attribution record from Apple and associates campaign metadata with the RevenueCat customer. You do not need to write your own server request to Apple’s attribution API when using this integration.
Use the public RevenueCat SDK key already configured for the app. Do not put a RevenueCat secret API key or Apple Ads credential in the client.
Standard versus Detailed attribution
The simple call above enables Standard attribution. RevenueCat documents that Standard attribution does not require App Tracking Transparency consent and can include attribution status, campaign ID, ad group ID, keyword ID, ad ID, country or region, conversion type, and claim type.
Detailed attribution can additionally include click and impression dates, but it requires the appropriate ATT flow. Do not add an ATT prompt only because you assume Apple Ads attribution always requires it. Decide whether the additional fields justify the permission request and follow RevenueCat’s current implementation guidance.
Apple may omit some dimensions in particular situations. For example, Search Match attribution may not include a keyword ID. A missing keyword does not automatically mean the whole integration failed.
Step 3: Ship the change and collect production data
Attribution begins helping only after users install or redownload a build that contains the SDK call. Release the updated app, keep the RevenueCat integration connected, and let relevant Apple Ads campaigns run.
Do not judge the setup from an existing customer who installed an older build. Debug and TestFlight environments may also produce placeholder or unspecified attribution data. Verify the code path during development, then use new production acquisition for the real check.
RevenueCat says the attribution token is processed with Apple within 24 hours and recommends allowing up to seven days for a new integration or campaign to gather attribution and purchase data. Trials also need time to convert before revenue appears.
Step 4: View Apple Search Ads revenue in Charts
After attributed users and transactions arrive, open a supported chart in RevenueCat and add an attribution filter or segment. RevenueCat provides:
- Attribution source: Apple Search Ads or Organic;
- Apple search ads campaign;
- Apple search ads group;
- Apple search ads keyword; and
- Apple search ads claim type: Click or Impression.
Use these dimensions with subscription, trial, revenue, lifetime value, and conversion charts that support attribution. Start with Attribution source = Apple Search Ads, then drill into campaign, ad group, and keyword only after the top-level totals look plausible.
Unspecified means RevenueCat received an attributed record without a usable name for that dimension. This can happen with Basic accounts, debug or TestFlight data, or fields Apple does not return for a particular match.
Step 5: Create an Audience of users acquired from ads
RevenueCat’s former Customer Lists feature is now called Audiences. Use it when you want to inspect the RevenueCat customer profiles behind the aggregate chart.
- Open Customers or Audiences in the RevenueCat project.
- Create a new custom Audience.
- Add the Media Source filter.
- Choose is not empty.
- Save it with a clear name such as Attributed acquisition users.
This works because RevenueCat stores the attribution source in the reserved $mediaSource customer attribute. Related attributes can include $campaign, $adGroup, $keyword, and Apple Ads campaign, ad group, and keyword IDs.
Important: “Media Source is not empty” includes every customer with a populated attribution source. If Apple Search Ads is the only attribution integration in the project, that may be exactly what you want. If Adjust, AppsFlyer, Branch, or another provider also sets $mediaSource, narrow the filter to Media Source = Apple Search Ads.
The Audience shows RevenueCat App User IDs and customer profiles, not necessarily a person’s real-world identity. Anonymous App User IDs are still useful for reviewing purchase history, total spent, attributes, and entitlement status.
Connect RevenueCat revenue to Apple Ads spend and ROAS
RevenueCat answers the revenue side of the question. Apple Ads answers the spend side. To calculate return on ad spend, compare attributed revenue with the corresponding campaign or keyword spend:
ROAS = attributed revenue ÷ ad spend
I use AdSwift to bring Apple Ads spend and RevenueCat revenue together in one Mac app. It saves the manual export and join, shows campaign and keyword ROAS, and provides a CLI for repeatable reports and automation.
ROAS is still an attribution result, not proof that every attributed purchase was incremental. Use it to compare paid-search decisions, then keep product quality, organic overlap, attribution windows, refunds, and long-term retention in view.
Troubleshooting checklist
| Symptom | Check |
|---|---|
| No attributed users | Confirm both the RevenueCat integration and the SDK attribution call are complete. |
| Only Basic-level data | Verify that Advanced is selected in RevenueCat and the connected Apple Ads account is the correct one. |
| Some campaigns are missing | Check Limited Access campaign groups or reconnect with the required scope. |
| Code is live but data is empty | Confirm new production installs used the updated build and allow time for attribution and purchases. |
| Campaign exists but keyword is unspecified | Check whether the conversion came from Search Match or another case where Apple did not return a keyword ID. |
| Audience contains other networks | Replace Media Source is not empty with Media Source equals Apple Search Ads. |
| Revenue is zero | Verify the customer purchased, the transaction reached RevenueCat, and trial conversion or renewal has had time to occur. |
RevenueCat’s Apple Search Ads attribution documentation is the source to recheck when the dashboard labels, SDK API, or supported dimensions change.
Frequently asked questions
Why is Apple Search Ads revenue not showing in RevenueCat?
The usual causes are an incomplete RevenueCat integration, a Basic and Advanced mismatch, missing Apple Ads account permissions, the AdServices attribution call missing from the app, no production release containing that call, or not enough time for new attributed installs and purchases to arrive.
Does RevenueCat Apple Search Ads attribution require ATT consent?
Standard AdServices attribution does not require ATT consent. Detailed attribution includes additional date fields and requires the appropriate ATT flow.
How can I see which RevenueCat users came from ads?
Create an Audience, formerly called a Customer List, and filter Media Source is not empty. If multiple attribution providers populate Media Source, filter specifically for Apple Search Ads.
Is Apple Search Ads the same as Apple Ads?
Apple Search Ads is the product’s former name and remains visible in some integrations and documentation. Apple now calls the product Apple Ads.