# Apple Search Ads Setup (/docs/paid-media/apple-setup)



The Apple Search Ads layer manages App Store Search Ads. It uses Apple's
OAuth flow (`appleid.apple.com/auth/oauth2/v2/authorize`, scope
`searchads`) — no Business Center / agency delegation involved.

## Prerequisites [#prerequisites]

* A verified iOS App Store listing on the project (see
  [Project settings → Apps](/docs/projects/settings-apps)).
* An Apple Search Ads account in good standing.
* Admin access on the ASA org so you can complete OAuth.

## Setup [#setup]

1. **Install the layer** from the catalog.
2. Click **Connect via OAuth**. You're redirected to Apple ID sign-in.
3. Grant Layers access (scope: `searchads`).
4. On return, configure campaign defaults (daily budget, geos, etc.)
   and save.
5. Bind the iOS app this layer manages.

## Billing [#billing]

Apple bills the card on file in your ASA account directly; Layers does
not sit in the billing path for Apple Search Ads.

## Layer config [#layer-config]

After OAuth, the connection is stored as `project_apple_ads_credentials`
(org ID, OAuth refresh token in vault). Layer-level config (campaign
type, geos, budget) lives in the layer's `config` JSONB — set through
the setup wizard rather than edited as raw JSON.

## Campaign types [#campaign-types]

| Type             | Where it shows                  |
| ---------------- | ------------------------------- |
| `search_results` | Top of organic search results.  |
| `search_tab`     | Search tab landing screen.      |
| `today_tab`      | Today tab feature placement.    |
| `product_pages`  | Above similar/recommended apps. |

The Apple Search Ads optimizer can manage all four. Configure the mix in
layer settings.

## Keywords [#keywords]

Layers' optimizer:

* Adds keywords from your search-term harvesting (terms that converted).
* Bids per keyword targeting your CPA goal.
* Pauses keywords with high spend / low conversion.

Manage keywords directly at
`/project/{projectId}/paid-media/apple/campaigns/{campaignId}/adgroups/{adgroupId}/keywords`.

## Search terms harvesting [#search-terms-harvesting]

Search terms (queries that triggered your ads) are visible at
`/project/{projectId}/paid-media/apple/search-terms`. From this view you
can:

* **Add as keyword** — promote a term to a managed keyword.
* **Add as negative** — block this term from triggering your ads
  (auto-syncs to [project keywords](/docs/projects/settings-keywords)
  if Negative category enabled).

## Attribution [#attribution]

Apple Search Ads attribution comes via the
`AAAttribution.attributionToken()` from the Layers SDK. The SDK reports
the token on first launch; Layers requests attribution data from Apple
on your behalf.

If you don't have the SDK installed, ASA attribution falls back to ASA's
own SKAdNetwork postbacks (lower fidelity).