Apple Search Ads

Apple Search Ads Management

Full management of Apple Search Ads campaigns for iOS apps using the ASA CLI tool.

Capabilities

This skill enables you to:

• Set up Apple's recommended 4-campaign structure
• Add keywords with automatic routing (exact → target, broad → discovery, negative → discovery)
• Block irrelevant search terms with negative keywords
• Promote winning keywords from Discovery to exact match campaigns
• Generate performance reports (campaign, keyword, search term level)
• Audit campaign structure against Apple's best practices
• Pause/enable campaigns
• Automated optimization - analyze search terms and batch promote/block keywords

Prerequisites

Running with uv (Recommended)

No installation required. Just use uv run:

cd /path/to/apple-search-ads-cli
uv run asa config setup
uv run asa campaigns list

Alternative: pip install

cd /path/to/apple-search-ads-cli
pip install -e .
asa config setup

Configuration

uv run asa config setup

You'll need from Apple Ads dashboard (https://ads.apple.com/):

• Organization ID
• Client ID, Team ID, Key ID
• Private key file (EC key pair)

To generate keys:

openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem

Verify Setup

asa config test

Command Reference

Configuration Commands

Campaign Commands

Ad Group Commands

Keyword Commands

Report Commands

Optimization Commands

Campaign Structure

Apple's recommended 4-campaign structure:

Keyword Routing

When you add keywords with --type brand/category/competitor:

1. EXACT match → Target campaign
2. BROAD match → Discovery (for mining related terms)
3. NEGATIVE → Discovery (prevents double-paying)

Common Workflows

Initial Setup

# 1. Configure (no installation required with uv)
cd /path/to/apple-search-ads-cli
uv run asa config setup
# Enter: Org ID, Client ID, Team ID, Key ID, private key path
# Enter: App ID, App name, Countries, Default bid

# 2. Test connection
uv run asa config test

# 3. Audit existing campaigns
uv run asa campaigns audit

# 4. Create 4-campaign structure (preview first)
uv run asa campaigns setup --countries US --budget 50 --dry-run
uv run asa campaigns setup --countries US --budget 50

Adding Initial Keywords

# Brand keywords (your app name)
asa keywords add "myapp,myapp app,my app" --type brand

# Category keywords (what your app does)
asa keywords add "photo editor,image filter,picture effects" --type category

# Competitor keywords (other apps)
asa keywords add "vsco,snapseed,lightroom" --type competitor

Weekly Optimization

Option 1: Automated (Recommended)

# Preview what will change
asa optimize --dry-run

# Run optimization with confirmation
asa optimize

# Or run automatically without prompts
asa optimize --auto-approve

The asa optimize command automatically:

1. Analyzes Discovery search terms (last 14 days)
2. Identifies winners (≥2 installs, CPA ≤ $5)
3. Identifies losers (≥$1 spend, 0 installs)
4. Promotes winners to target campaign (adds as exact + negative in Discovery)
5. Blocks losers across all managed campaigns

Option 2: Manual

# 1. Check overall performance
asa reports summary --days 7

# 2. Find winning search terms
asa reports search-terms --winners

# 3. Promote winners to exact match
asa keywords promote "best photo app,picture editor free" --target category

# 4. Find wasted spend
asa reports search-terms --negatives

# 5. Block wasteful terms
asa keywords add-negatives "auto clicker,signal app,testflight,crypto trading" --all

Troubleshooting

# Check campaign structure issues
asa campaigns audit --verbose

# List all campaigns including non-managed
asa campaigns list --all

# Check specific campaign keywords
asa keywords list --campaign 12345

# Check negative keywords
asa keywords list --negatives --campaign 12345

Campaign Naming

The CLI identifies campaign types by looking for these keywords in the campaign name (case-insensitive):

Examples of valid names:

• Brand (simple)
• My Brand Campaign
• MyApp Category
• competitor-us

Example Keywords

Brand Keywords (your app/company name)

[appname], [appname] app, [company] invest

Category Keywords (what your app does)

photo editor, image filter, picture effects, camera app

Competitor Keywords (competing apps)

[competitor1] app, [competitor2], [competitor3]

Common Negative Keywords (block these)

auto clicker, signal app, testflight, crypto trading, forex trading, stock trading, day trading

API Coverage

The CLI covers these Apple Search Ads API operations:

Not yet implemented (advanced features):

• Creative sets
• Geo-targeting beyond country level
• Budget orders

API Notes

Bulk Operations: The CLI uses Apple's bulk API endpoints for keyword operations (enable, pause, delete, update bid). These are more efficient than individual requests.

Caching: Apple's API may show stale data after delete operations. If keywords still appear in listings after deletion, the delete was successful but the cache hasn't refreshed. Attempting to modify deleted keywords will return "keyword deleted" errors.

Search Terms Reports: Search term reports require campaigns to have accumulated sufficient data (typically a few days of activity). New campaigns may return empty results.

Error Handling: Keyword add operations (add_keywords, add_negative_keywords) return both successful additions and any errors (e.g., duplicate keywords). The CLI displays both:

• Successfully added keywords are shown in green
• Duplicates or other errors are shown with details but don't fail the overall operation

Authentication Retry: The CLI automatically retries requests (up to 2 times) when authentication tokens expire, refreshing the token transparently.

Documentation

• Apple Best Practices: https://ads.apple.com/app-store/best-practices/campaign-structure
• Apple API Docs: https://developer.apple.com/documentation/apple_ads