Apple Search Ads — Conquest Campaigns

A Claude Code skill (and standalone Node toolkit) for running Apple Search Ads with a competitor-conquesting strategy: bid on rival apps' brand names so users who discovered a competitor through its TikTok/Instagram ads — then search that competitor in the App Store — land on your app instead.

You intercept high-intent demand your competitors paid to create.

Works as an AI-driven skill or as a plain CLI. Point Claude Code at a new app and it will research competitors, build the keyword set, create the campaign, and set up daily auditing — or run the toolkit yourself.

What's inside

.
├── SKILL.md                         # the skill: when/how Claude runs the workflow
├── references/
│   ├── setup.md                     # credentials + keypair (one-time)
│   ├── workflow.md                  # the 6-phase conquest workflow, CLI reference
│   └── competitor-research-prompt.md# research subagent prompt template
├── templates/
│   ├── campaign.example.json        # campaign config for the one-shot creator
│   └── keywords.example.json        # keyword list shape (EXACT match)
└── toolkit/                         # dependency-free Node CLI (API v5)
    ├── auth.js  client.js  asa.js   # OAuth, API client, CLI
    ├── create-conquest.js           # one-shot: campaign → ad group → keywords
    ├── daily-audit.js  daily-audit.sh # daily performance audit + cron wrapper
    ├── discover-org.js              # find your orgId/currency from the API
    ├── .env.example  package.json  .gitignore

Requirements

• Node.js ≥ 20 (uses native fetch and crypto — zero dependencies)
• An Apple Ads account with Account Admin access to create an API user
• openssl (for the one-time keypair)

Quick start

git clone <this-repo> && cd <this-repo>

# 1. Credentials (details in references/setup.md)
cd toolkit && mkdir -p secrets && umask 077
openssl ecparam -genkey -name prime256v1 -noout -out secrets/private-key.pem
openssl ec -in secrets/private-key.pem -pubout -out secrets/public-key.pem
cd ..
cp toolkit/.env.example .env         # fill in ASA_CLIENT_ID/TEAM_ID/KEY_ID/CURRENCY
#   (upload toolkit/secrets/public-key.pem in the Search Ads UI to get those IDs)

# 2. Verify + discover org
node --env-file=.env toolkit/discover-org.js   # prints orgId + currency → put orgId in .env
node --env-file=.env toolkit/asa.js test        # → ✅ Authenticated

# 3. Create a conquest campaign (starts PAUSED)
cp templates/campaign.example.json campaign.json
cp templates/keywords.example.json keywords.json
#   edit both: your adamId, countries, budget (in your currency), competitor keywords
node --env-file=.env toolkit/create-conquest.js campaign.json

# 4. Review, then go live
node --env-file=.env toolkit/asa.js keywords <campaignId> <adGroupId>
node --env-file=.env toolkit/asa.js campaign-status <campaignId> ENABLED

# 5. Daily audit (local cron — see references/workflow.md)
node --env-file=.env toolkit/daily-audit.js

Using it as a Claude Code skill

Copy this directory into your skills folder (~/.claude/skills/apple-search-ads-conquest). Then just tell Claude Code about an app — e.g. "launch an Apple Search Ads conquest campaign for <App Store link>" — and it will follow SKILL.md: research the competitors, assemble the keywords, create the campaign (paused for your review), and wire up the daily audit.

Notes

• All amounts are in your account currency (ASA_CURRENCY). Examples use USD; use figures sensible for your currency and market.
• Your private key never leaves your machine. .env, secrets/, and the token cache are git-ignored. Never commit them or place credentials in a cloud/CI config.
• New campaigns need a learning ramp — don't judge or prune on the first few days.
• This project is not affiliated with or endorsed by Apple. "Apple Ads" / "Apple Search Ads" are trademarks of Apple Inc. Use in accordance with Apple's terms.

License

MIT — see LICENSE.