apple-search-ads-conquest

---
name: apple-search-ads-conquest
description: Use when setting up, launching, or managing an Apple Search Ads (Apple Ads) campaign for an app — especially a competitor-conquesting strategy that bids on rival apps' brand names to intercept App Store search intent created by their TikTok/Instagram ads. Triggers on "apple search ads", "ASA campaign", "conquest campaign", "bid on competitors", "advertise my app on the app store", or bringing a new app idea to promote.
---

# Apple Search Ads — Conquest Campaigns

## Overview

Create and manage Apple Search Ads campaigns using a **conquest** strategy: bid on
competitor apps' brand names so users who discovered a rival through its
TikTok/Instagram ads — then search that rival in the App Store — land on **your**
app instead. You intercept high-intent demand competitors paid to create.

Ships with a dependency-free Node CLI (Apple Ads Campaign Management API v5), a
one-shot campaign creator, and a daily audit. **All amounts are in the account
currency** (`ASA_CURRENCY`).

## When to use
- Setting up Apple Search Ads for a new or existing app
- Building a competitor/conquest keyword strategy
- Creating campaigns, ad groups, keywords; adjusting bids/budgets
- Standing up automated daily performance auditing

**Not for:** Google/Meta/TikTok ad platforms, ASO/organic keywords, or App Store
Connect build/metadata tasks.

## Prerequisites (one-time)

API credentials + local keypair. **REQUIRED:** follow `references/setup.md`
(generate EC keypair → create an *API Account Manager* user → upload public key →
`.env` → `discover-org.js` → `asa.js test`). The private key stays local.

## Workflow

Full detail in `references/workflow.md` — read it before executing. The phases:

1. **Understand the app** — WebFetch its App Store listing; record the numeric `adamId`, category, positioning, and any rivals it names.
2. **Research competitors** — dispatch a web-research subagent using `references/competitor-research-prompt.md`; get apps actively marketing on TikTok/IG + brand-term variants.
3. **Build keywords** — `keywords.json`: competitor brands + generics + your own brand-defense, EXACT match, bids in account currency (`templates/keywords.example.json`).
4. **Create (paused)** — fill `campaign.json` (`templates/campaign.example.json`), run `create-conquest.js` → campaign+adgroup+keywords in one shot with `startPaused: true`.
5. **Review & go live** — inspect keywords, then `campaign-status <id> ENABLED`. Expect a multi-day learning ramp.
6. **Daily audit** — set `ASA_TARGET_CPA`/`ASA_BRAND_PREFIXES`, schedule `daily-audit.sh` via **local cron** (needs the local key — never a cloud job).

## Quick reference

```bash
# from repo root, after setup
node --env-file=.env toolkit/asa.js test
node --env-file=.env toolkit/create-conquest.js campaign.json     # create (paused)
node --env-file=.env toolkit/asa.js campaign-status <cId> ENABLED # go live
node --env-file=.env toolkit/daily-audit.js                       # audit now
```

Full command table: `references/workflow.md`. Every `asa.js` subcommand prints usage if run without args.

## Common mistakes
- **Judging a new campaign too early.** Zero-impression keywords in the first days are noise; wait for the ramp before pruning.
- **Wrong currency in bids.** `bidAmount.currency` in `keywords.json` must match the account currency, and amounts must be sensible for it (e.g. ~$2, not 2 dollars written as 200).
- **Read-only API role.** "API Account Read Only" blocks all writes — use *API Account Manager*.
- **Cloud-scheduling the audit.** A cloud agent can't reach your local private key. Use local cron.
- **No brand-defense.** Without bidding your own name, competitors conquest you back on your own TikTok-driven searches.
- **Over-bidding on day one.** Start near `target_CPA × expected conversion rate`; scale from data.