Apple Search Ads Setup
Connect Apple Search Ads via OAuth. Keywords, ad groups, search-term harvesting.
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
- A verified iOS App Store listing on the project (see Project settings → Apps).
- An Apple Search Ads account in good standing.
- Admin access on the ASA org so you can complete OAuth.
Setup
- Install the layer from the catalog.
- Click Connect via OAuth. You're redirected to Apple ID sign-in.
- Grant Layers access (scope:
searchads). - On return, configure campaign defaults (daily budget, geos, etc.) and save.
- Bind the iOS app this layer manages.
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
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
| 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
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 (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 if Negative category enabled).
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).