# Apple Ads

Connect the account in [Apple Ads](https://submetry.com/app/apple-ads). The form starts empty. Submetry marks the account connected only after Apple accepts its OAuth credentials and a campaign-report read succeeds.

## Prepare read access

In Apple Ads Advanced, invite an API user with a read-only API role. Generate an ES256 key pair and upload the public key under Account Settings → API. Copy the Client ID, Team ID and Key ID that Apple displays, plus your Organization ID. This is the Apple Ads API setup, separate from App Store Connect API credentials.

The Submetry form accepts a PKCS#8 private key (`BEGIN PRIVATE KEY`, .p8 or .pem). If Apple’s OpenSSL example generated a SEC1 `BEGIN EC PRIVATE KEY`, convert it locally:

```sh
openssl pkcs8 -topk8 -nocrypt -in private-key.pem -out private-key.p8
```

Paste the private key and identifiers in Submetry. Credentials are encrypted on the server with AES-GCM, bound to the Submetry organization, and never returned by the API. Submetry requests short-lived Apple OAuth access tokens as needed; it does not change campaigns or bids.

## Read actual reports

Choose UTC start/end dates and load the report. The account-level table reads Apple’s Campaign Management API v5 and shows spend in the original account currency, impressions, taps, total installs and CPI. Empty results stay empty. Mixed spend currencies are not combined into one monetary total.

Attributed gross revenue comes only from resolved `install_attribution` events joined to actual RevenueCat or Superwall production purchases using the same installation/user identity. Unmatched revenue remains unavailable, displayed as `—`. Purchasers without a matching identity cannot be assigned to a campaign. ROAS is calculated only for USD spend, because Submetry does not invent exchange rates.

## Install attribution

The Swift SDK requests an AdServices token automatically once per installation on iOS 14.3+. Set `appleAdsAttribution: false` when configuring to disable it. AdServices runs off the main thread. Supply the same user ID to Submetry and your financial provider so server purchases can be joined to the installation.

Submetry resolves the token only through Apple’s fixed HTTPS attribution endpoint, retries an Apple 404 up to three attempts, and stores allowlisted resolved fields. It removes the token before event/raw persistence. A failed resolution remains unresolved and contributes no campaign revenue. Other downloadable adapters do not automatically access native AdServices; bridge native attribution deliberately if your app needs it.

## Endpoints

Account session required: `GET`, `POST`, `DELETE /v1/providers/apple-ads`; `GET /v1/providers/apple-ads/reports?from=YYYY-MM-DD&to=YYYY-MM-DD`. Organization-scoped read-only keys and app server keys cannot manage or read this account connection.

Apple Ads live access requires your account credentials. Local crypto/report tests verify the protocol and parsing; they do not establish that a real account is connected.

References: [Apple OAuth](https://developer.apple.com/documentation/apple_ads/implementing-oauth-for-the-apple-search-ads-api), [campaign reports](https://developer.apple.com/documentation/apple_ads/get-campaign-level-reports), [AdServices tokens](https://developer.apple.com/documentation/adservices/aaattribution/attributiontoken()).
