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:
ads:meta:adAccount: act_1234567890 # optional: the account picked in Appeekycampaigns: ["120210000000001"]tiktok:advertiser: "7000000000000" # optionalcampaigns: ["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:
$ 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.
$ npx @appeeky/spec search-ads pull✓ appeeky/search-ads/ US Exact, Discovery30 days: 412.80 EUR · 236 installs · 1.75 EUR each · 980 taps48 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
$ npx @appeeky/spec ads --save2026-10-05 → 2026-11-04 (30 days, per day)Apple Search Ads spend $42.10 installs 31.2 cost per install $1.35Meta spend $28.40 installs 18.7 cost per install $1.52TikTok spend $15.00 conversions 6.1 cost per conversion $2.46Saved 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.
$ npx @appeeky/spec experiment add --type ads --metric meta_cpi --hypothesis "Rain video lowers Meta CPI" --days 14Started 2026-11-04-rain-video-lowers-meta-cpi · check on 2026-11-18baseline 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.