Apple Search Ads

Files (10)

• SKILL.md
• _meta.json
• api-reference.md
• ios-integration.md
• measurement.md
• memory-template.md
• scripts.md
• setup.md
• strategy.md
• troubleshooting.md

SKILL.md (first lines)

Toolkit for Apple Search Ads (rebranded "Apple Ads" in 2024; API paths still read `searchads`): Campaign Management API v5, attribution (AdServices + SKAdNetwork), bid math, diagnosis, and scaling strategy. All local state (config, memory, campaign notes, reports) lives in `~/Clawic/data/apple-search-ads/` (see `setup.md` on first use, `memory-template.md` for file formats). If you have data at an old location (`~/apple-search-ads/` or `~/clawic/apple-search-ads/`), move it to `~/Clawic/data/apple-search-ads/`, and say in one line that you moved it and from where. Credentials are never stored here: the five `ASA_*` values are read from your environment or key file at call time, they are the standard set Apple's Campaign Management API requires for JWT auth (client, team, key, org, private key), and every spend-changing call is confirmed with you first (see `confirm_before_push`).

## Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in `~/Clawic/data/apple-search-ads/config.yaml`.

| Variable | Type | Default | Effect |
|---|---|---|---|
| currency | string (ISO code) | USD | Currency for every bid, budget, and CPA example; passed in all API money objects |
| report_timezone | UTC \| ORTZ | UTC | Passed as `timeZone` in every report request — one value everywhere, never mixed (Traps) |
| ltv_divisor | number (3-5) | 4 | Target CPA = LTV / `ltv_divisor`; 3 = aggressive payback, 5 = conservative (`strategy.md`) |
| mmp | none \| appsflyer \| adjust \| singular \| kochava \| branch | none | With an MMP set, it owns AdServices and SKAN integration and cross-channel truth (`ios-integration.md`, `measurement.md`) |
| confirm_before_push | bool | true | Every API mutation (bids, budgets, status, keywords) is listed and confirmed before pushing; false = push and log without asking. Setting it to false means real ad spend changes without a prompt: only do it for campaigns you own and can afford to have moved unattended; campaign DELETE stays confirmed either way |
| naming_pattern | text | App - Country - Intent | Template for every campaign name in create payloads, scripts, and memory logs; parsing reports assumes this pattern |

Preference areas to record as the user reveals them:

- **tooling** — dashboard vs API/scripts, report automation cadence; decides whether plays are given as UI steps or curl commands
- **conventions** — ad group naming, experiment tagging, negative-list hygiene; shapes create payloads and memory logs
- **markets** — home market, expansion order, localization resources; shapes Multi-Country guidance in `strategy.md`
- **risk posture** — payback aggressiveness, scaling speed within the 20-30% step band, how proactively to flag overspend
- **reporting** — source of truth per KPI, deliverable format and cadence; shapes `measurement.md` reconciliation and report outputs

## When To Use

- Launching or restructuring campaigns for an iOS app
- Optimizing bids, budgets, keywords, or CPA on running campaigns
- Diagnosing problems: no impressions, budget not spending, CPA spikes, rejected ads, API errors, mismatched install counts
- Wiring attribution (AdServices, SKAdNetwork, MMP) into the app and deciding which numbers to trust
- Automating reports and weekly optimization via the API
- Deciding scaling, multi-country expansion, or Custom Product Page tests
- Mode: acts directly via the API when the user grants credentials; otherwise advises on structure and strategy. Not for App Store metadata/screenshot work itself — route to `aso`; this skill only flags when CVR points there.

## Quick Reference

Route by what you need to do. Read one file; each is self-contained.

| Situation | Go to |
|-----------|-------|
| First run, `~/Clawic/data/apple-search-ads/` missing, loading preferences | `setup.md` |
| Saving apps, targets, campaign structure, learnings to memory | `memory-template.md` |
| Authenticating, base URL/headers, endpoints, payloads, campaign/ad group/keyword objects, report requests, metrics, error codes, rate limits | `api-reference.md` |
| No impressions, spend with no installs, budget not spending, CPA suddenly spiked, campaign ON_HOLD or rejected, API 401/403/429 | `troubleshooting.md` |
| Adding attribution in the iOS app (AdServices, SKAdNetwork conversion values, MMP integration, testing) | `ios-integration.md` |
| Choosing a source of truth, reconciling ASA vs SKAN vs MMP counts, estimating LTV, brand-spend incrementality, cohort ROAS | `measurement.md` |
| Planning structure, placements, match types, keyword tiers, bidding, benchmarks, budget allocation, scaling, multi-country, Custom Product Pages | `strategy.md` |
| Running curl/jq automation (get token, daily/search-term/keyword reports, add keywords/negatives, weekly optimization) | `scripts.md` |
| Anything else | Apply Core Rules below, then route to the closest file |

## Core Rules

### 1. Bid Backwards From LTV, Never From Competitors' Bids
Max CPT = target CPA × expected CVR. Target CPA $6 and CVR 50% → max CPT $3.00. A bid above your max CPT needs an explicit reason (brand defense); a bid copied from "what the niche pays" has none. CPA math lives in `strategy.md`; LTV estimation in `measurement.md`.

### 2. Structure Is the Strategy: One Intent Per Campaign
Brand, category, competitor, discovery — separate campaigns. ASA has no portfolio bid strategies or shared budgets; campaign separation is the only budget and reporting control you get, so mixing intents removes your only lever.

### 3. "Exact Match" Is Not Exact
ASA exact match also serves plurals and common misspellings (Apple-documented). Before concluding a keyword works or fails, open the search term report and see which queries actually spent the money.

### 4. Graduate and Negate
Weekly: any search term with ≥2 installs and CPA ≤ target → add as exact match in its intent campaign AND as a negative where it was discovered. Skip the negative and the discovery campaign keeps buying the term, splitting its data forever.

### 5. Defend Your Brand
Competitors WILL bid your name, and your relevance advantage makes brand defense the cheapest CPA in the account. Impression share is reported as a range, not a point; if the high bound on brand terms sits below ~90%, raise brand bids. Whether brand spend is incremental at all is testable — holdout protocol in `measurement.md`.

### 6. One Country Per Campaign
CPT, CVR, and query language differ per market; blended reporting makes every bid decision wrong somewhere. Separate campaigns per country/region.

### 7. Spend Gates Before Scale
Keyword spend ≥ 2× target CPA with 0 installs → cut the bid sharply (30-50%) or pause. Example: target CPA $6 → any keyword that burned $12 with no install acts today, not at month end.

### 8. Bid Your True Max — the Auction Is Second-Price
Apple has described the auction as second-price: you pay just above the next-highest bid. Shading below your max CPT mostly loses auctions; it rarely saves money. Cap risk with the spend gate (Rule 7), not with timid bids.

## Output Gates

Before pushing any change through the API:

- Is the new bid computed from max CPT (Rule 1), not from current bid ± gut feel?
- One variable per keyword/ad group per cycle (bid OR creative OR match type)?
- Is the decision backed by the minimum window in `strategy.md` (7 days; 14 for competitor campaigns), and does that window end ≥2 days back (recent rows still backfill — `measurement.md`)?
- Budget increase within the 20-30% step limit (`strategy.md` → Scaling)?
- If `confirm_before_push` is true (default), was the change list shown and confirmed?
- Change and expected effect logged to `~/Clawic/data/apple-search-ads/memory.md`?

## Architecture

Memory lives in `~/Clawic/data/apple-search-ads/`. See `memory-template.md` for structure.

```
~/Clawic/data/apple-search-ads/
├── config.yaml        # Declared variables (Configuration table above)
├── memory.md          # Active campaigns, preferences, learnings
├── credentials.md     # OAuth config (NEVER commit real secrets)
├── campaigns/         # Campaign-specific notes and performance
│   └── {app-id}/
├── reports/           # Generated reports
└── scripts/           # Custom automation
```

## Traps

| Trap | Why it fails | Do instead |
|------|--------------|------------|
| Treating `cpaGoal` as a spend cap | It is advisory; Apple can spend far past it | Control CPA with bids and the spend gate (Rule 7) |
| Refining age/gender to "focus" targeting | Excludes every user with Personalized Ads off — a large, invisible slice | Stay broad; segment by keyword intent instead |
| Search Match ON in every ad group | Your own ad groups compete for the same queries; data fragments | Search Match only in the discovery campaign |
| Same bid across all keywords | Brand, category, and long-tail have different values | Tier bids off max CPT (`strategy.md`) |
| Judging dayparting by install timestamps | SKAN postbacks arrive hours to days late | Daypart on tap timestamps |
| Comparing ASA dashboard installs to MMP installs | Different attribution windows and models; they never match | Pick one source of truth per KPI (`measurement.md`); record it in memory.md |
| Reading today's report rows as final | Installs attribute retroactively to their tap date across the 30-day window | Judge windows that end ≥2 days back; treat newer rows as provisional |
| Launching on a weak product page | You pay per tap; low CVR taxes every dollar | Fix ASO first, then buy traffic |
| Mixing timezones across reports | ASA reports accept UTC or ORTZ; mixing misaligns days | Set `report_timezone` once and pass it in every request |
| No cross-campaign negatives | Category/discovery campaigns quietly buy your brand queries at brand-level CPTs | Add brand terms as negatives in every non-brand campaign |
| Scaling budget in big jumps | Volume spikes re-enter auctions at worse positions; CPA jumps | 20-30% per step (`strategy.md` → Scaling) |

## Where Experts Disagree

From clawic/skills, MIT.

More from clawic/skills