> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Experiments and screenshots

> Track screenshot, UGC, ads and pricing experiments next to your listing, write personas once, and check screenshot sizes.

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:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.appeeky.com/docs/spec-ai-visibility.md)) |
| `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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.appeeky.com/docs/spec-commands.md#attribution-init)), `--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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.appeeky.com/docs/spec-own-keys.md#apple-search-ads). Meta and TikTok ad accounts usually promote more than one app, so list the campaigns that belong to this one:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.appeeky.com/docs/spec-screenshots.md).

Uploading screenshots is not part of Appeeky Spec yet. Use the [App Store Connect CLI](https://docs.appeeky.com/docs/store-cli-app-store-connect.md) for uploads.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.