appeeky spec
← Learn

Paid growth · 5 min read

Your ads, next to your listing

Apple Search Ads, Meta and TikTok in the spec: list the campaigns, save the numbers, and run ad tests as experiments.

A new subtitle can lower what an install costs you on ads, and a new ad can lift organic search. Keeping ads in the same repo as the listing means both are judged on the same days, with the same numbers.

The three channels

  • Apple Search Ads

    Matched to the app in Appeeky, or read with your own API key.

  • Meta

    List the campaigns that promote this app.

  • TikTok

    List the campaigns and the advertiser.

Connect each channel in Appeeky first. The spec reads them with your APPEEKY_API_KEY.

List your campaigns

Ad accounts usually promote more than one app, so the spec only counts the campaigns you name:

appeeky.spec.yaml
ads:
meta:
adAccount: act_1234567890 # optional: the account picked in Appeeky
campaigns: ["120210000000001"]
tiktok:
advertiser: "7000000000000" # optional
campaigns: ["1790000000000"]

Search Ads on your own key

No Appeeky account needed for Search Ads. In Apple Search Ads → Account Settings → API, invite an API user with a read role and upload its public key. Then save it on the App Store Connect CLI account that already holds your App Store Connect key:

zsh
$ appstore accounts search-ads my-team --client-id SEARCHADS.… --team-id SEARCHADS.… --key-id … --private-key-path searchads.pem
{ "ok": true, "account": "my-team", "searchAds": true }

The private key stays in the CLI, and the spec calls Apple through it. In GitHub Actions, where there is no CLI account, set ASA_CLIENT_ID, ASA_TEAM_ID, ASA_KEY_ID and ASA_PRIVATE_KEY as secrets instead.

zsh
$ npx @appeeky/spec search-ads pull
✓ appeeky/search-ads/ US Exact, Discovery
30 days: 412.80 EUR · 236 installs · 1.75 EUR each · 980 taps
48 keywords, 210 search terms. Read appeeky/search-ads/summary.md.

Only the campaigns for your App Store app are read; stores.appStore.searchAds picks the organization and campaigns when you need to. The summary lists the search terms people typed and installed from that are not targets yet. Ranking for those organically costs nothing, so they are the first targets to try. It also lists the keywords that spent and brought nothing. ads and verify read these files, and the daily routine pulls them when the key is set.

Read and save the numbers

zsh
$ npx @appeeky/spec ads --save
2026-10-05 → 2026-11-04 (30 days, per day)
Apple Search Ads spend $42.10 installs 31.2 cost per install $1.35
Meta spend $28.40 installs 18.7 cost per install $1.52
TikTok spend $15.00 conversions 6.1 cost per conversion $2.46
Saved appeeky/ads/2026-11-04.yaml

--save keeps a dated copy in appeeky/ads/, so the history sits in git next to the listing. TikTok reports conversions: whatever event the campaign optimizes for.

Ads around a listing push

Every verify check compares the ad numbers before and after the push too: Search Ads installs and cost per install, Meta spend, installs and cost per install, TikTok spend and cost per conversion. A listing that converts better often shows up first as a cheaper install.

Ad tests as experiments

A new creative or audience is an experiment with one metric. The baseline comes from the days before; verify closes it on the check date.

zsh
$ npx @appeeky/spec experiment add --type ads --metric meta_cpi --hypothesis "Rain video lowers Meta CPI" --days 14
Started 2026-11-04-rain-video-lowers-meta-cpi · check on 2026-11-18
baseline meta_cpi 1.52 (last 14 days)

Metrics you can use: cpa and ad_installs for Search Ads, meta_cpi and meta_installs, tiktok_cpa and tiktok_conversions.