BillDog

View saved version →

---
name: billdog-analyst
description: Answer questions about a BillDog project's numbers - revenue, MRR and ARR, churn, renewals, billing issues, trial conversion, LTV, paywall and placement conversion, revenue by country, product, offering, paywall or experiment arm, funnels, retention and event trends. Use when the user asks how their app, subscriptions or paywalls are doing, why revenue or conversion changed, or wants a weekly recap. Read-only.
---

# Analysing a BillDog project

Every number comes from `run_analytics_query` and a few list tools on the BillDog
MCP server. Nothing here changes the project.

## Before you answer

- **Pick the right (source, metric).** Use the table below. If a question does not
  fit it, call `discover_schema` once: it lists every valid pairing with a one-line
  hint, and an unsupported pairing fails.
- **Ranges** are `{ start, end }` as full UTC timestamps ending in `Z`, for example
  `2026-10-15T00:00:00Z`. Use the last 30 days when the user names no range, and say so.
  End at today's 00:00 UTC for whole days, or at the current time to include today
  so far, and say which.
- **Environment.** Queries read production unless you pass `sandbox: true`. Every
  result says which one it read in `environment`. If production comes back empty or
  all zero, retry with `sandbox: true` and tell the user the figures are test data.
  A project that is still being integrated often has only sandbox data.
- **Freshness.** `revenue` figures come from a daily rollup. `revenue` / `totals`
  carries `meta.freshness`: days after `final_through` are provisional or missing.
  Other reports do not carry it, so when the range ends in the last two days, run
  `revenue` / `totals` once for the same range and say which days are not final, so a
  short week is not read as a drop.
- **Every source and metric in the table below is valid**, including
  `revenue_segments`, `subscription_charts`, `subscription_cohorts`, `trial_cohorts`
  and `ltv_prediction`. If your copy of the tool's schema lacks one, it is out of
  date: `discover_schema` gives the current list.

## Which query answers which question

| Question | Query |
|---|---|
| Revenue, refunds, MRR, ARR, active subscriptions, churn rate, trial conversion, ARPU, new customers, all in one call | `revenue` / `totals` |
| This period against the last one | `revenue` / `compare` with `range.compare_to: "previous_period"` (or `"previous_year"`) |
| New, expansion, contraction, churned and net MRR | `subscriptions` / `mrr_movement` |
| Revenue by country, store, platform, product, offering, paywall or placement | `revenue_segments` / `breakdown` with `dims: ["<one of those>"]` |
| Revenue by experiment arm | `revenue_segments` / `breakdown`, `dims: ["experiment_variant"]`, `filters.experiment_id` |
| Top products | `products` / `top_n`, or `revenue_segments` / `top_n` with `dims: ["product"]` |
| Paywall impressions, purchases and conversion per paywall | `paywalls` / `breakdown` (grouped by paywall) |
| Presented, started, purchased | `paywalls` / `funnel` |
| Trial conversion by trial-start week or month | `revenue` / `trial_cohorts` with `range.granularity` |
| Renewal rate, billing issues and recovery, plan changes, ARPPU | `subscription_charts` / `totals` (or `timeseries`) with `filters.chart`: `renewal_rate`, `billing_issues`, `plan_changes` or `arppu` |
| Subscription retention, realized and predicted LTV | `subscription_cohorts` / `retention`, `breakdown` or `ltv_prediction` |
| A funnel across app events | a saved view first (`list_saved_views` → `get_saved_view_results`); else `events` / `funnel` with `filters.event_names` in order |
| Event volume, trends, top events | `events` / `timeseries`, `top_n` or `breakdown`; `list_event_names` for exact names |
| A paywall A/B test | `get_experiment_results` (see the billdog-experiments skill) |

Two easy mistakes: `revenue` / `breakdown` is revenue **per day**, and
`revenue` / `top_n` is the top **days**. Neither s

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: billdog-experiments
description: Run BillDog paywall A/B experiments and feature flags. Use when the user asks to test two paywalls against each other, start, pause, end or ship the winner of a BillDog experiment, read experiment results, or create, roll out, turn off or read a BillDog feature flag.
---

# BillDog experiments and feature flags

Both are managed over the BillDog MCP server. Anything that changes what live
users see needs the user's go-ahead first; ask before each such call.

## Paywall A/B experiments

An experiment shows a different paywall per variant at the same place in the
app. The app code does not change: the SDK resolves the placement and BillDog
assigns the variant.

1. **Look first.** `list_placements`, `list_paywalls` and `list_experiments`.
   Only one experiment can run on a paywall at a time.
2. **Every variant's paywall must be published** before the experiment can
   start. Build one with `list_templates` → `create_paywall_from_template` or
   `design_paywall`, then `preview_paywall`, then `publish_paywall` (ask first).
3. **Create** with `create_experiment`. It is saved as a draft and serves
   nothing. The first variant is the control unless one says `is_control`.
   Traffic splits evenly unless every variant gives `traffic_percent`, which must
   add up to 100.
4. **Start** with `start_experiment` (ask first). On a live project the start
   waits for an owner or admin to approve it: when the result says
   `awaiting_approval`, give the user its `approve_url`.
5. **Read results** with `get_experiment_results`: users, conversions, revenue
   per user, lift against the control, p-value and a verdict of `winner`,
   `loser`, `keep_running` or `no_data`. A result is significant only at
   p < 0.05 with 100+ users per arm. Do not call a winner on `keep_running`.
6. **Finish** with `stop_experiment` (ask first):
   - `pause` sends everyone back to the control and can be started again.
   - `end` does the same and cannot be restarted.
   - `ship_winner` with `winner_variant_id` serves the winner to everyone.

Results read production unless you pass `sandbox: true`. An experiment tested
only on a development build will show `no_data` in production.

## Feature flags

1. **Look first.** `list_feature_flags`. Reuse an existing key rather than
   creating a near-duplicate.
2. **Create** with `create_feature_flag`. It is created off: every user gets
   false. For a multivariate flag give two or more `variants` whose
   `rollout_percentage` adds up to 100, each with an optional JSON payload.
3. **Wire it into the app** by key. Look up the flag getter for the platform in
   https://billdog.io/docs/feature-flags or with `get_sdk_integration_guide`;
   do not guess a method name. Handle the "off" value as the default path.
4. **Roll out** with `update_feature_flag` (ask first). Turning it on needs a
   `rollout_percentage` above 0; 100 means everyone. Start small when the user
   has not said otherwise. On a live project the change may wait for approval.
5. **Check exposure** with `get_feature_flag_results`: users and evaluations per
   value over the last 1–90 days, counted from the `$feature_flag_called` events
   the SDKs send. Zero evaluations after a release usually means the app does
   not read the flag yet, or reads a different key.

Audience rules (release conditions) are edited in the BillDog dashboard, not over
MCP. If the user asks for targeting, say so and link
https://billdog.io/docs/feature-flags.

View saved version →

---
name: billdog-headless
description: Build a custom (bring-your-own-UI, headless) paywall on BillDog - fetch the offering a placement selects for this user, draw it with the app's own UI (SwiftUI, Jetpack Compose, React Native, Expo, Flutter, web, or a game engine over REST), buy a package, and handle holdout, withheld, gated and unknown placements and impressions correctly. Use when the user wants their own paywall screen instead of a BillDog-designed one, mentions headless or BYO-UI paywalls, or integrates BillDog into Unity, Unreal, Godot, a TV or desktop app without an SDK.
---

# Headless (bring-your-own-UI) paywalls

In headless mode the server decides **what** to sell to this user (the offering,
from the placement, its campaigns and experiments) and the app decides **how** to
show it. The app never receives a designed paywall: `paywall` is always null.

The full guide with complete samples for every platform is
https://billdog.io/docs/headless-paywalls (Markdown:
https://billdog.io/docs/headless-paywalls.md). Use it for anything this file does
not cover; do not guess an SDK method.

## The rules, on every platform

1. **Use the placement identifier the project has.** Read it with `list_placements`
   over the BillDog MCP server, or ask. An unknown placement is 404
   `PLACEMENT_NOT_FOUND`, surfaced as a typed error. It never falls back to another
   offering, so show nothing and report the typo.
2. **`offering` is the selection, and it can be null.** Null means nothing was
   selected for this user: show nothing. Do not take an entry from `offerings`
   instead, and do not fall back to the current offering.
3. **Read `presentation` before drawing.** All of these arrive as a normal success:
   - `holdout: true`: this user is in a holdout. Show nothing.
   - `withheld: true` (sent only when true), with `withheld_reason` `holdout` or
     `audience_excluded`: `offering` is null on purpose.
   - `gated: true` with `required_entitlement`: reaching this screen needs access,
     and in headless mode the app owns that gate. Check the entitlement and let a
     user who has it through.
4. **Track only what you showed.** Call `trackPaywallPresented(offering, placement)`
   when the screen appears and `trackPaywallDismissed(offering, placement)` with the
   same offering when it goes away. Never track for a holdout, a withheld result or
   a null offering: a holdout is measured by the absence of an impression. No
   `paywall_id` is sent.
5. **Fetch when you are about to show it.** A read that resolves a running
   experiment or campaign records the exposure and counts the campaign impression
   (and its frequency cap) whether or not the screen appears. Don't prefetch screens
   the user may never reach.
6. **Unlock from entitlements, not from the purchase call alone.** After a purchased
   or restored result, read customer info and check the entitlement the screen
   sells.
7. **Prices come from the store product on the package**, not from the offering's
   metadata. Never write a price into copy.

## Platform API

| Platform | Fetch | Result | Buy / restore | Unknown placement |
|---|---|---|---|---|
| iOS | `try await BillDog.shared.getOffering(placement:)` | `PlacementOffering`: `offering`, `presentation`, `shouldPresent` | `BillDog.shared.purchase(package:)` → `PurchaseResult`; `BillDog.shared.restore()` | throws `BillDogError.placementNotFound` |
| Android | `BillDog.getOffering(placement)` (suspend; `BillDog` is a Kotlin `object`) | `PlacementOffering` with `shouldPresent` | `BillDog.purchase(activity, pkg)` → `PurchaseResult`; `BillDog.restorePurchases()` → `RestoreResult` | throws `BillDogException`, `error` is `BillDogError.PlacementNotFound` |
| React Native, Expo | `BillDog.getOffering(placement)` | `OfferingResult`: `offering`, `presentation`, `placement` | `BillDog.purchasePackage(pkg)` and `BillDog.restore()` never throw; switch on `result.type` | rejects with `PlacementNotFoundError` |
| Flutter | `BillDog.share

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: billdog-integration
description: Wire the BillDog SDK into an app, or diagnose one that is already wired. Use when the user asks to add BillDog, set up paywalls or subscriptions with BillDog, add BillDog analytics/surveys/messaging, fix a BillDog integration that shows nothing, or asks why a BillDog paywall is not appearing.
---

# Integrating BillDog

BillDog is paywalls, analytics, messaging, surveys, journeys and auth behind one
SDK and one dashboard.

The exhaustive per-platform reference — every install line, every docs URL — is
served at **https://billdog.io/SKILL.md**. Fetch it when you need a platform this
file does not cover. What follows is the procedure and the things that are easy
to get wrong.

## Diagnose before you change anything

A project is already wired if any of these exist: `.billdog.json`,
`@billdog.io/*` in `package.json`, `io.billdog:billdog-*` in a Gradle file, or
`billdog-ios-spm` in `Package.resolved`.

If it is wired, the problem is usually a missing placement or a missing identify
call — not a missing install. Diagnose first: call the MCP tool
`get_setup_status`, which returns exactly what is missing with dashboard links.

There is no published BillDog CLI on npm; `npx billdog` will fail. Without the
MCP server, verify by hand using the checklist at the end.

## Identifiers

Getting these wrong is the single most common failure, because neither fails
until install or compile time:

| | Correct | Does not exist |
|---|---|---|
| npm scope | `@billdog.io/…` | `@billdog/…` |
| Maven group | `io.billdog:…` | `com.billdog:…` |

- **Web** — `npm install @billdog.io/web`
- **React Native** — `npm install @billdog.io/react-native`
- **Expo** — `npm install @billdog.io/expo`
- **iOS** — SPM `https://github.com/billdogai/billdog-ios-spm`, products
  `BillDogFull` (everything) or `BillDogEng` (engagement only). Different
  modules, different public surfaces — pick one and import only that.
- **Android** — `io.billdog:billdog-core`, `io.billdog:billdog-analytics`,
  `io.billdog:billdog-auth`, and siblings. Entry point `io.billdog.core.BillDog`,
  a Kotlin `object`.

## Configure

The web SDK is a **default-exported singleton**. There is no `new BillDog(...)`
and no `init()`:

```ts
import BillDog from '@billdog.io/web';

BillDog.configure({
  apiKey: process.env.BILLDOG_API_KEY,
  environment: 'production',
});

// When your user signs in:
await BillDog.logIn('user_123');
```

## Placements

A placement is the named spot where a paywall can appear. Code references the
**placement identifier**, never a paywall id — that is what lets the paywall
change without a release. Create one under Paywalls → Placements.

A project with a valid key and an installed SDK but no placement is wired
correctly and still shows nothing. That is the most common "it doesn't work".

## Critical rules

- **Public keys in client code. Never a secret key.** If the user offers a
  secret key for a mobile or web app, say so and ask for the public one.
- **Never commit a key.** If there is no ignored env file, create one and add it
  to `.gitignore` in the same change.
- **Configure once, early** — before any other SDK call.
- **Identify before fetching a paywall**, or the user is anonymous and targeting
  will not match.
- **Do not invent identifiers.** If a package, class or method is not in this
  file or at https://billdog.io/SKILL.md, look it up. A plausible guess here
  costs a failed build in someone else's repo.

## Verify before reporting success

1. The SDK package is in the dependency manifest.
2. `configure` runs before any other BillDog call.
3. A customer id is set before any paywall fetch.
4. A placement identifier in code matches one in the dashboard.
5. Events appear under Analytics → Live within a minute.

## Reading and setting up the project over MCP

This plugin ships the BillDog MCP server (`https://api.billdog.io/mcp`). The
first call opens "Sign in with BillDog" in the browser; the user picks one
project 

Preview of the first 4,000 characters. Read full instructions →