> For the complete AppRefer docs index, see https://apprefer.com/llms.txt (every page as markdown) or https://apprefer.com/llms-full.txt (all docs in one file).

# Apple Ads

AppRefer attributes installs from Apple Ads (Apple Search Ads) through Apple's AdServices framework, with no setup in your app, and can import your Apple Ads spend for cost and ROAS.

## Attribution

On first launch the iOS SDK (and the Flutter and React Native SDKs on iOS) asks AdServices for an attribution token and sends it with `configure`. AppRefer exchanges it with Apple and, if Apple says the install came from an Apple Ads campaign, attributes it to network `apple_ads` with match type `adservices`. There are no entitlements or prompts to add; it needs iOS 14.3 or later.

-   Apple's answer is checked first, before any click matching, because it comes from Apple itself.
-   It works whatever the user answered to the tracking prompt. An install whose user denied tracking can still be attributed to Apple Ads, but to nothing else.
-   AppRefer stores the campaign, ad group, keyword, ad (creative set), country or region, conversion type and click date that Apple returns, so you can break revenue down by keyword.
-   If Apple returns no attribution, the install goes through the normal matching (see [Attribution](https://apprefer.com/docs/attribution.md)).

> **No conversions are sent to Apple**
>
> Apple Ads has no conversions API, so AppRefer never forwards events to it, and Apple Ads installs are never part of the organic fan-out to other networks. Apple measures its own installs, plus [SKAdNetwork postbacks](https://apprefer.com/docs/integrations/skan.md).

## Spend sync

To see Apple Ads cost next to revenue, connect an Apple Ads API user. In Apple Ads, go to **Account Settings → API**, create an API user, upload your public key and note the **client ID**, **team ID**, **key ID** and your **organisation ID**. Then generate a client secret (a JWT signed with your private key) as Apple's API guide describes.

1.  In **Settings → Integrations → Apple Search Ads**, enter the organisation ID, client ID and client secret and save.
2.  If your Apple Ads organisation advertises more than one app, set `adamId` (or `adamIds`) through the API so only this app's campaigns are imported.

**PATCH /api/v1/apps/{appId}/integrations/apple_ads**

```json
{
  "orgId": "1234567",
  "clientId": "SEARCHADS.…",
  "clientSecret": "eyJ…",
  "adamId": "1234567890"
}
```

| Field | Meaning |
| --- | --- |
| `orgId` | Apple Ads organisation ID. Required. |
| `clientId` | API client ID. Required, secret. |
| `clientSecret` | Client secret JWT you generated. Secret. |
| `adamId, adamIds` | Your App Store app ID(s). Filters the campaign report to these apps. Without it, every campaign in the organisation counts as this app's spend. |
| `granularReports` | Optional. Also import ad group, keyword and search-term spend for the busiest campaigns (15 by default, up to 50 with granularReportCampaignLimit). |

The integration shows as connected once the organisation ID, client ID and a client secret are stored; there is no connection test. AppRefer imports campaign spend, impressions and taps per day, stored in the currency Apple reports for each campaign. You can also use the MCP tool `configure_integration` with network `apple_ads`.

> **Client secrets expire**
>
> Apple client secrets last at most 180 days. When yours expires, spend sync stops with an authentication error until you generate a new one and save it.

### Self-hosted deployments

If you run AppRefer yourself, it can sign a fresh client secret on every sync instead. Store the private key in an environment variable named `APPLE_ADS_<NAME>_PRIVATE_KEY` and set `teamId`, `keyId` and `privateKeyEnv` (the variable's name) on the integration, leaving `clientSecret` empty. On a deployment shared by several organisations, also set `APPLE_ADS_PRIVATE_KEY_ORGS` (`ENV_NAME=orgA|orgB,OTHER_ENV=orgC`) so each key can only be used by the AppRefer organisations it is bound to; any other organisation naming that variable is refused.

---

Source: https://apprefer.com/docs/integrations/apple-ads · Last updated: 2026-10-19