Your paid channels, next to the listing
A new subtitle can make an install cheaper on ads, and a new ad can lift organic search. With both in one repo, they are judged on the same days with the same numbers.
Apple Search Ads
Matched to the app in Appeeky, so it needs nothing in the spec. Or read straight from Apple on your own key.
Meta
Ad accounts usually promote more than one app, so you list the campaigns that belong to this one.
TikTok
The same: the campaigns under ads.tiktok, with the advertiser when it is not the one picked in Appeeky.
Only the campaigns you name
Connect Meta and TikTok in Appeeky first. Then list the campaigns under ads:; spend from other apps in the same ad account never mixes in. adAccount and advertiser default to the ones picked in Appeeky.
ads:meta:adAccount: act_1234567890 # optionalcampaigns: ["120210000000001"]tiktok:advertiser: "7000000000000" # optionalcampaigns: ["1790000000000"]
Spend, installs, cost per install
ads prints each channel over the last --days (30 by default, up to yesterday). TikTok reports conversions: whatever event the campaign optimizes for.
--save writes a dated copy to appeeky/ads/, so the history sits in git beside the listing it ran with. Reading Meta and TikTok needs your APPEEKY_API_KEY.
$ npx @appeeky/spec ads --save2026-10-05 → 2026-11-04 (30 days, per day)Apple Search Ads spend $42.10 installs 31.2 per install $1.35Meta spend $28.40 installs 18.7 per install $1.52TikTok spend $15.00 conversions 6.1 per conv. $2.46Saved appeeky/ads/2026-11-04.yaml
Apple Search Ads on your own key
No Appeeky account needed for Search Ads. The key is saved once on the App Store Connect CLI account that already holds your App Store Connect key, and never enters the repo.
Save the key where your store key lives
In Apple Search Ads, open Account Settings, then API, invite an API user with a read role and upload its public key. Save the key on the CLI account; the spec calls Apple through it.
In CI, where there is no CLI account, set ASA_CLIENT_ID, ASA_TEAM_ID, ASA_KEY_ID and ASA_PRIVATE_KEY as secrets instead. They win over the account.
$ appstore accounts search-ads my-team \--client-id SEARCHADS.… --team-id SEARCHADS.… \--key-id … --private-key-path ./searchads-private-key.pem
Paid searches, as files
Only the campaigns for your App Store app are read. daily.csv keeps spend, installs, taps and impressions per day across pulls, next to keywords.csv and search-terms.csv.
summary.md lists the searches that installed but are not targets yet (free to rank for, so the first to try) and the keywords that spent and brought nothing.
When the key reaches more than one organization, stores.appStore.searchAds.orgId picks it, and campaigns narrows the read. ads and verify read these files, and the daily routines pull them when ASA_CLIENT_ID is set.
$ npx @appeeky/spec search-ads pull✓ appeeky/search-ads/ US Exact, Discovery30 days: 412.80 EUR · 236 installs · 1.75 EUR each · 980 tapsdaily.csv · keywords.csv · search-terms.csv · summary.md
Judged on the same days as the listing
Every listing push is checked on day 7 and day 14. The ad numbers are part of that check, and an ad test is an experiment of its own.
Ads around every push
verify compares the days before and after a push for Search Ads installs and cost per install, and for the spend, installs and cost per install of the Meta and TikTok campaigns under ads:.
A listing that converts better often shows up first as a cheaper install. If cost per install fell and organic ranks rose, the listing did it. If only spend changed, the ad team did.
$ npx @appeeky/spec verify2026-11-03 · subtitle push · day 14 · wonbetter organic installs/day 31 → 38 (+23%)better organic revenue/day $41.20 → $47.90 (+16%)better cpa $1.35 → $1.12flat meta_cpi $1.52 → $1.47 (moves ±9% on its own)
A new creative is an experiment
One metric, a baseline from the days before, and a check date. verify closes it when it is due. The ad metrics: cpa and ad_installs for Search Ads, meta_cpi, meta_installs, tiktok_cpa and tiktok_conversions.
$ npx @appeeky/spec experiment add --type ads \--metric meta_cpi --days 14 \--hypothesis "Rain video lowers Meta CPI"Started 2026-11-04-rain-video-lowers-meta-cpi · check on 2026-11-18baseline meta_cpi 1.52 (last 14 days)
What the ads specialist does with it
A search that converts on ads but is not a target is the strongest evidence for a new one. Moving money stays with a person.
Every install, with where it came from
Attribution tags each install with where it came from (organic store search, an Apple Search Ads keyword, a smart link, the Google Play referrer) and follows it to trials and purchases.
Self-hostedvia: self
The free Workers plan is enough to start
The data never leaves your account
No Appeeky account needed
Hosted by Appeekyvia: hosted
Turn it on in the app's Attribution tab
Nothing to run
The SDK in your app
It records the install, where it came from and the screens. No IDFA and no tracking prompt: the install id is a random id kept in the app. The Expo plugin brings the native module that reads the Apple Search Ads token and the Google Play install referrer.
There is one for React Native and Expo, Swift, Kotlin and Flutter. Each starts with the publishable key and links the install to the RevenueCat customer (or the Superwall user), so a purchase finds its source.
$ npm install @appeeky/analytics-expo
import Appeeky from "@appeeky/analytics-expo";import Purchases from "react-native-purchases";Appeeky.init({ key: "apk_..." });// Link the install to the RevenueCat customer, so purchases find their source.Appeeky.identify(await Purchases.getAppUserID());
Purchases come from your paywall
Trials and purchases reach the server from RevenueCat or Superwall webhooks, not from the app. The SDK only says which user an install belongs to, so the server can match the purchase to the install and its source. Sandbox purchases are ignored.
attribution init finds or creates the app for each store, writes attribution: to the spec and prints the SDK key and the RevenueCat webhook to add. Without --self, it turns on the hosted service.
$ npx @appeeky/spec attribution init \--self https://analytics.sleepsounds.workers.devFound App Store app app_ios123 · key apk_pub_mSp…Created Google Play app app_and456 · key apk_pub_qcZ…Wrote attribution: to appeeky.spec.yaml.
One app per store
An app in Appeeky Analytics is one platform. For an app on both stores, give one id per store: each release is measured with its own store's installs.
attribution:via: selfurl: https://analytics.sleepsounds.workers.devapp:app-store: app_ios123google-play: app_and456# or, on Appeeky's service:# attribution: { via: hosted, app: "1234567890" }
Organic installs and revenue decide the release
Ranks are a means. A listing change is for more people finding the app in search and paying for it, so that is what decides.
Installs
1,580
all sources
Organic
1,097
69% of installs
Revenue
$2,100
from these installs
Organic / day
33 → 42
after the subtitle push
Nov 2 · day 8 after push
- Organic44
- Search Ads14
- Smart links4
Revenue $96
Install sources
- Organic search1097$1,344
- Apple Search Ads411$630
- Smart links72$126
$ npx @appeeky/spec verify
subtitle push · day 7: won
better organic installs/day 33 → 42
Countries
- USUnited States695
- DEGermany269
- GBUnited Kingdom221
- BRBrazil158
- TRTürkiye126
- JPJapan111
One release, decided by what it brought
With attribution: set, verify compares organic installs per day, their revenue and the share that paid, before and after each push.
Smart links, and the numbers as files
A TikTok post, a creator video or an ad has no listing of its own to measure. A smart link gives it one number to be judged on.
A link per experiment
experiment add --link creates one URL that sends each visitor to the right store, with its installs and revenue counted to it. Measure it on link_installs, link_revenue or link_clicks; verify closes it when it is due.
The App Store passes nothing from a click to a new install, and there is no device fingerprinting, so link installs are in practice Google Play installs. For an App Store only app, measure link_clicks or organic installs around the post.
$ npx @appeeky/spec experiment add --type ugc \--link tiktok --metric link_installs --target 50 \--hypothesis "Before/after hooks get installs"Started 2026-11-04-before-after-hooks-get-installslink https://analytics.sleepsounds.workers.dev/l/ab12xy
What your agent reads
data pull writes App Store Connect, Google Play, Apple Search Ads, RevenueCat, Meta and TikTok per day, and with attribution: five more files: where installs and revenue came from.
With a self-hosted server, the attribution files need no Appeeky key. They are your private numbers, so they stay in the gitignored .appeeky/data/ unless you set data: { commit: true }.
.appeeky/data/· with attribution: · gitignored
- attribution-sources.csvinstalls, trials, payers and revenue by source and campaign
- attribution-keywords.csvSearch Ads keyword ids, with the revenue they led to
- attribution-campaigns.csvthe same, per campaign
- attribution-countries.csvper country
- smart-links.csvclicks, installs and revenue per link
The commands
- ads
- Spend, installs and cost per install per channel over --days (30). Needs APPEEKY_API_KEY.
- ads --save
- The same, written to appeeky/ads/<date>.yaml.
- search-ads pull
- Apple Search Ads on your own key into appeeky/search-ads/, with the search terms that are not targets yet.
- attribution init
- Create the app in Appeeky Analytics per store, write attribution: and print the SDK key. --self <url> for your own server.
- verify
- Ads, organic installs and their revenue before and after every push.
- experiment add --type ads
- An ad test with one metric: meta_cpi, tiktok_cpa, cpa, ad_installs…
- experiment add --link
- A smart link for a post, a creator or an ad, measured on its installs, revenue or clicks.
- data pull
- Every source per day as CSV, and attribution by source, keyword, campaign, country and link.
Guides
- Paid growth · 5 min readYour ads, next to your listingApple Search Ads, Meta and TikTok in the spec: list the campaigns, save the numbers, and run ad tests as experiments.
- Measuring · 8 min readMeasure installs with attributionSelf-host Appeeky Analytics on Cloudflare or use Appeeky's, measure organic installs and revenue per push, and give experiments their own links.
- Measuring · 9 min readSet up attribution in your appRun Appeeky Analytics yourself on Cloudflare or use Appeeky's, add the SDK, connect RevenueCat, check the first install and point the spec at it.