Experiments and screenshots

Listing pushes measure themselves. Everything else you try to grow the app (new screenshots, a UGC video, an ad angle, a price change) goes in appeeky/experiments/, with one metric and a date to check it.

Personas

Write who the app is for once, in appeeky.spec.yaml, so screenshots, UGC and ads speak to the same people:

personas:
  - id: sleepless-parent
    name: Sleepless parent
    searches: [baby sleep sounds, white noise for baby]
  - id: light-sleeper
    name: Light sleeper in a city flat
    searches: [noise blocker, sleep with noise]

Start an experiment

npx @appeeky/spec experiment add \
  --type ugc \
  --persona sleepless-parent \
  --hypothesis "Before/after hooks get more installs" \
  --metric install_per_1k_views \
  --baseline 1.8 --target 2.5 \
  --days 14 \
  --asset https://www.tiktok.com/@sleepsounds/video/123

One experiment, one metric. If you cannot name the number that decides it, it is not ready to run.

Type	Typical metric
`screenshots`	`conversion`
`ugc`	Installs per 1,000 views
`ads`	`cpa`, `ad_installs`, `meta_cpi`, `tiktok_cpa`
`pricing`	`trial_conversion`, `revenue`

Metrics measured for you

These metrics need no --baseline or --value: add measures the baseline over the same number of days before the start, and verify measures the result once the experiment is due and closes it. Each one needs its source. The automatic baseline comes from Appeeky. Without APPEEKY_API_KEY, pass --baseline for metrics read from your repo (ad_installs and cpa from your own Search Ads pull, ai_visibility from your own scans, search_clicks, search_impressions). Smart link metrics are read from the link’s last 30 days.

Metric	Meaning	From
`conversion`	Downloads ÷ product page views	App Store Connect, Google Play (`APPEEKY_API_KEY`)
`page_views`, `downloads`, `proceeds`, `trials`	Per day	App Store Connect, Google Play (`APPEEKY_API_KEY`)
`revenue`, `rc_trials`, `trial_conversion`	Per day; trial conversion as a rate	RevenueCat (`APPEEKY_API_KEY`)
`ad_installs`, `cpa`	Installs per day, cost per install	Apple Search Ads (Appeeky, or `search-ads pull` on your own key)
`meta_spend`, `meta_installs`, `meta_cpi`	Per day, cost per install	Meta campaigns under `ads:`
`tiktok_spend`, `tiktok_conversions`, `tiktok_cpa`	Per day, cost per conversion	TikTok campaigns under `ads:`
`organic_installs`, `organic_revenue`, `organic_paid`	Organic installs per day, their revenue, the share that paid	`attribution:`
`link_clicks`, `link_installs`, `link_revenue`	Clicks, installs and revenue from the experiment’s smart link	`attribution:` and `--link`
`rating`, `low_ratings`	Average rating, share of 1–2 star reviews	`appeeky/reviews/`
`ai_visibility`	Share of AI answers that name the app	`appeeky/visibility/` (AI answers)
`search_clicks`, `search_impressions`	Google clicks and impressions per day	`appeeky/seo/daily.csv`
`web_rank`, `ai_overview_citations`	The site’s average Google position; share of AI Overviews that cite it	`appeeky/seo/ranks.csv`
`category_rank`	Rank in the category chart	`appeeky/category.csv`

For cpa, meta_cpi, tiktok_cpa, spend, low_ratings, web_rank and category_rank, lower is better.

npx @appeeky/spec experiment add --type pricing \
  --hypothesis "Showing the annual plan first lifts trial conversion" \
  --metric trial_conversion --days 14

Without a --target, a measured experiment is won when the metric moved at least 5% the right way, lost when it moved 5% the wrong way, and inconclusive otherwise.

Smart links

With attribution: set up (attribution init, see Commands), --link creates a smart link for the experiment: one URL that sends each visitor to the right store, with its installs and revenue counted to it.

npx @appeeky/spec experiment add --type ugc --link tiktok \
  --hypothesis "Before/after hooks get installs" --metric link_installs --target 50
# Started 2026-11-04-before-after-hooks-get-installs
#   link https://analytics.sleepsounds.workers.dev/l/ab12xy

On iOS the App Store passes nothing from a click to a new install, so link installs are, in practice, Google Play installs. For an App Store only app, measure link_clicks (or organic_installs).

Paid channels

Apple Search Ads needs nothing in the spec: it is matched to the app in Appeeky, or read with search-ads pull on your own key. Meta and TikTok ad accounts usually promote more than one app, so list the campaigns that belong to this one:

ads:
  meta:
    adAccount: act_1234567890      # optional: defaults to the account picked in Appeeky
    campaigns: ["120210000000001"]
  tiktok:
    advertiser: "7000000000000"    # optional: defaults to the advertiser picked in Appeeky
    campaigns: ["1790000000000"]

Connect Meta and TikTok in Appeeky first. ads prints spend, installs (conversions for TikTok) and cost per result per channel, and --save keeps a copy in appeeky/ads/. verify compares the same numbers before and after every push, so a listing change and an ad change are judged on the same days.

Check and close

npx @appeeky/spec experiment list
npx @appeeky/spec experiment close 2026-11-01-before-after-hooks-get-more-installs --value 2.7 --playbook

list marks experiments past their check date. close compares --value with the target: reaching it is won, missing it is lost. For a metric Appeeky measures, close without --value measures it. --playbook adds the result to appeeky/playbook.md, next to the listing results.

Screenshots

npx @appeeky/spec screenshots pull
npx @appeeky/spec screenshots check

pull downloads the live App Store screenshots of every locale into appeeky/screenshots/app-store/<locale>/<display type>/. check validates their pixel sizes against the display type and counts them. Put your new screenshots in the same folders and check validates those before you upload. The pull request report fails on screenshot errors too. push does not upload screenshots, so it only warns about them. See Screenshots. Uploading screenshots is not part of Appeeky Spec yet. Use the App Store Connect CLI for uploads.

Get started

Your listing

Know your market

Grow

Automate

Reference

Personas

Start an experiment

Metrics measured for you

Smart links

Paid channels

Check and close

Screenshots

​Personas

​Start an experiment

​Metrics measured for you

​Smart links

​Paid channels

​Check and close

​Screenshots

Personas

Start an experiment

Metrics measured for you

Smart links

Paid channels

Check and close

Screenshots