Know which installs your listing brought, and what they paid

Apple Search Ads, Meta and TikTok next to the listing, and every install tagged with where it came from, followed to trials and purchases.

Then ask your agent: “Set up Appeeky Spec for this app.”

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.

appeeky.spec.yaml
ads:
meta:
adAccount: act_1234567890 # optional
campaigns: ["120210000000001"]
tiktok:
advertiser: "7000000000000" # optional
campaigns: ["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.

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 per install $1.35
Meta spend $28.40 installs 18.7 per install $1.52
TikTok spend $15.00 conversions 6.1 per conv. $2.46
Saved 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.

once, on your machine
$ 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.

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
daily.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.

zsh
$ npx @appeeky/spec verify
2026-11-03 · subtitle push · day 14 · won
better organic installs/day 31 → 38 (+23%)
better organic revenue/day $41.20 → $47.90 (+16%)
better cpa $1.35 → $1.12
flat 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.

zsh
$ 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-18
baseline 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.

install
$ npm install @appeeky/analytics-expo
app/_layout.tsx
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.

zsh
$ npx @appeeky/spec attribution init \
--self https://analytics.sleepsounds.workers.dev
Found 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.

appeeky.spec.yaml
attribution:
via: self
url: https://analytics.sleepsounds.workers.dev
app:
app-store: app_ios123
google-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.

analytics.sleepsounds.workers.dev/apps/sleep-sounds
Sleep SoundsAttributionLast 30 days

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

Organic Search Ads Smart links Revenue
Oct 7subtitle push · Oct 25Nov 5

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.

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.
Every command in the docs

Guides

More in Appeeky Spec