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

# Paid channels

> See spend, installs and cost per install for Apple Search Ads, Meta and TikTok next to your listing, and measure ad changes with the same verify and experiments as listing changes.

`ads` puts your paid channels in one table: Apple Search Ads, Meta and TikTok, with spend, installs and cost per install. Keep a copy in the repo, and `verify` and experiments judge an ad change on the same days as a listing change.

## Where each channel comes from

| Channel | Through Appeeky (`APPEEKY_API_KEY`) | On your own key |
| - | - | - |
| Apple Search Ads | Matched to the app in Appeeky; nothing in the spec | `search-ads pull` writes `appeeky/search-ads/`, and `ads` reads it. See [Apple Search Ads on your own key](https://docs.appeeky.com/docs/spec-search-ads.md) |
| Meta | The campaigns listed under `ads.meta` | Not available |
| TikTok | The campaigns listed under `ads.tiktok` | Not available |

When `appeeky/search-ads/` exists, `ads` and `verify` use it for Apple Search Ads, even with `APPEEKY_API_KEY` set. Without `APPEEKY_API_KEY`, `ads` shows only Apple Search Ads from the repo.

## List your Meta and TikTok campaigns

Apple Search Ads needs nothing in the spec. Meta and TikTok ad accounts often promote more than one app, so list the campaigns that belong to this one in `appeeky.spec.yaml`:

```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. Each block needs at least one campaign id.

## See the numbers

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @appeeky/spec ads
```

```
2026-10-09 → 2026-11-08 (30 days, per day)
Apple Search Ads   spend $13.77     installs 7.87     cost per install $1.75
Meta               spend $40.00     installs 21.5     cost per install $1.86
TikTok             spend $25.00     conversions 9.2      cost per conversion $2.72
```

Every number is per day over the window, which ends yesterday (today is not over yet). For TikTok the result is conversions of the campaign's optimization event, not installs.

| Flag | Meaning |
| - | - |
| `--days <n>` | How many days, up to yesterday (default 30) |
| `--save` | Also write the numbers to `appeeky/ads/<date>.yaml` |
| `--json` | Print the snapshot as JSON |

A channel that cannot be read is listed in red with the reason; the others still print. With no data at all, `ads` tells you to connect the channels in Appeeky and list the Meta and TikTok campaign ids.

## The ads files

`ads --save` writes `appeeky/ads/<date>.yaml`, named after the end of the window, so the repo keeps a history of ad performance next to the listing:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
from: 2026-10-09
to: 2026-11-08
days: 30
currency: USD
channels:
  - channel: apple-search-ads
    spendPerDay: 13.77
    resultsPerDay: 7.87
    costPerResult: 1.75
    result: installs
  - channel: meta
    spendPerDay: 40
    resultsPerDay: 21.5
    costPerResult: 1.86
    result: installs
  - channel: tiktok
    spendPerDay: 25
    resultsPerDay: 9.2
    costPerResult: 2.72
    result: conversions
```

`to` is exclusive: the window is `from` up to the day before `to`. A second save on the same day replaces that day's file.

For day-by-day numbers, `data pull` writes `apple-search-ads.csv`, `meta-ads.csv` and `tiktok-ads.csv` to `.appeeky/data/` (needs `APPEEKY_API_KEY`). See [Commands](https://docs.appeeky.com/docs/spec-commands.md).

## The ad metrics

`verify` compares these before and after every push, and experiments can use any of them as their one metric:

| Metric | What it is | Better |
| - | - | - |
| `ad_installs` | Apple Search Ads installs per day | Up |
| `cpa` | Apple Search Ads cost per install | Down |
| `meta_spend` | Meta spend per day | Down |
| `meta_installs` | Meta installs per day | Up |
| `meta_cpi` | Meta cost per install | Down |
| `tiktok_spend` | TikTok spend per day | Down |
| `tiktok_conversions` | TikTok conversions per day | Up |
| `tiktok_cpa` | TikTok cost per conversion | Down |

So a listing change and an ad change are judged over the same days. A new subtitle that lifts organic installs while Search Ads installs stay flat reads differently from one that only moved paid installs.

## Run an ad experiment

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @appeeky/spec experiment add --type ads \
  --hypothesis "Parent-focused creative lowers Meta cost per install" \
  --metric meta_cpi --target 1.5 --asset 120210000000001
```

With `APPEEKY_API_KEY`, the baseline is the metric over the same number of days before the start. Otherwise pass `--baseline` yourself. On the check date, `verify` measures the metric and closes the experiment. See [Experiments](https://docs.appeeky.com/docs/spec-experiments.md).

## Who acts on it

The ads specialist in the weekly review reads Apple Search Ads, Meta, TikTok and attribution data. It returns what the paid searches teach the listing (searches worth adding as targets) and spend findings for a person to act on. It only reads: campaigns and budgets stay yours to change. See [Agents](https://docs.appeeky.com/docs/spec-agents.md).

Related: [Apple Search Ads on your own key](https://docs.appeeky.com/docs/spec-search-ads.md) · [Experiments](https://docs.appeeky.com/docs/spec-experiments.md) · [Attribution](https://docs.appeeky.com/docs/spec-attribution.md)


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