# SplitHub

> Analytics and A/B testing for websites and mobile apps built with coding agents, in one install. Analytics properties collect pageviews (or app screens) and `track()` events (reports by page, source, channel, country, device, platform, app version and UTM; funnels, paths, retention, realtime); experiments (A/B, multivariate, redirect) are declared in `splithub.config.ts` or the dashboard, rendered with `@splithub/react`, `@splithub/next` or `@splithub/react-native` (or the drop-in script; iOS and Android have native SDKs), and the verdict is read from the `splithub` CLI, the `@splithub/mcp` server or the dashboard. Events go to your own database (self-hosted, free) or to SplitHub Cloud (50,000 free exposures, pageviews and events per project per month, packs from $5, Pro $19/month).

One command sets everything up in a project: `npx splithub` (interactive) or `npx splithub init --mode cloud --yes` (agents). The CLI installs agent skills (.claude/skills, .cursor/rules) and an MCP server entry, so Claude Code, Cursor and Codex know how to add analytics, create experiments and read both. `npx splithub analytics connect` adds an analytics property to the app.

Apps: React Native and Expo use `@splithub/react-native` (`npx splithub init` detects them and wraps the entry); native iOS uses the Swift package `SplitHub` and Android `io.splithub:splithub` (both new, version 0.1.0). Screens are page events; targeting takes `platform` and `app_version` (`gte` / `lt`, dotted versions compared part by part); reports break down by platform and app version; events wait on the device while offline; app experiments start and change in the dashboard without a store release.

Every docs page below is also available as raw Markdown by appending `.md` to its URL. The whole documentation in one file: https://splithub.io/llms-full.txt

How agents get access to a cloud project (browser approval by a human, no self-registration): https://splithub.io/auth.md


## Start

- [Getting started](https://splithub.io/docs/getting-started.md): Set up SplitHub in a website or an app, collect pageviews, screens and events, create an experiment and read its verdict.
- [How it works](https://splithub.io/docs/concepts.md): Config file as source of truth, analytics properties, deterministic assignment, exposures and goals, self-hosted vs cloud.
- [splithub.config.ts](https://splithub.io/docs/config.md): Every field of the config: storage, goals, properties, experiments, variants, traffic, schedule, targeting.

## Analytics

- [Analytics](https://splithub.io/docs/analytics.md): Properties, setup in one command, automatic pageviews, track() and identify(), events and goals, one install with experiments.
- [Reports](https://splithub.io/docs/analytics-reports.md): Dimensions (platform and app version too), filters, compare, segments, funnels, paths, retention cohorts, realtime, export, notes and alerts.

## Experiments

- [Redirect experiments](https://splithub.io/docs/redirect-experiments.md): Test whole pages: match a path, send each variant to its own URL with middleware, a script or short links.
- [Targeting flows](https://splithub.io/docs/targeting.md): Country, device, UTM, cookie, time, platform and app version conditions as a node graph, in the dashboard and in the config.
- [Goals and revenue](https://splithub.io/docs/goals.md): Any event as a goal, pageview and click goals, revenue props, attribution by first exposure.
- [Statistics and verdicts](https://splithub.io/docs/statistics.md): A sequential test that is safe to peek, SRM check, minimum sample, data-quality stars, guardrails, when a verdict is final.

## SDKs

- [React](https://splithub.io/docs/react.md): SplitHubProvider with a property, <Experiment>/<Variant>, useVariant, useValue, useTrack, useIdentify, automatic pageviews.
- [Next.js](https://splithub.io/docs/nextjs.md): Middleware, Server Components, redirect experiments without flicker, live overrides, analytics on the provider.
- [Drop-in script](https://splithub.io/docs/script.md): sh.js for sites without a build step: pageviews and events with data-property, redirect experiments, splithub.track and identify.

## Apps

- [Apps](https://splithub.io/docs/apps.md): A/B testing and analytics in mobile apps: screens as page views, app version targeting, offline events, retention, and why app experiments live in the cloud.
- [React Native and Expo](https://splithub.io/docs/react-native.md): @splithub/react-native: install with npx splithub init, SplitHubProvider, Expo Router and React Navigation screens, hooks, offline queue, release builds.
- [iOS (Swift)](https://splithub.io/docs/ios.md): The SplitHub Swift package for iOS and macOS: SplitHub.start, variants and values, SwiftUI SplitHubExperiment, screens, events, offline and QA.
- [Android (Kotlin)](https://splithub.io/docs/android.md): io.splithub:splithub for Android: SplitHub.start in Application, variants and values, Jetpack Compose Experiment and TrackScreen, offline and QA.

## Tools

- [CLI reference](https://splithub.io/docs/cli.md): init (websites, React Native, Expo, iOS, Android), create, start/pause/finish, status, results, analytics, push, pull, login, doctor, skills.
- [MCP server](https://splithub.io/docs/mcp.md): @splithub/mcp for Claude Code, Cursor and Codex: tools for experiments and analytics on websites and apps, setup, working rules.
- [Agent skills](https://splithub.io/docs/agent-skills.md): The nine skills the CLI installs and how an agent uses them to run experiments and analytics correctly, on websites and in apps.
- [HTTP API](https://splithub.io/docs/api.md): Ingest of exposures, goals, pageviews and events, experiment and property endpoints, key scopes, live overrides JSON, errors.

## Cloud and data

- [Self-hosted (your database)](https://splithub.io/docs/self-hosted.md): The ingest handler, the Store interface, Postgres/MySQL/SQLite/D1, the events table, attribution SQL, raw analytics counts.
- [SplitHub Cloud](https://splithub.io/docs/cloud.md): Dashboard for analytics and experiments, projects, keys, live overrides, event gate, retention, what is billed.
- [Alerts, digest, AI reviews](https://splithub.io/docs/alerts.md): Rules that pause or finish tests, channels, the scheduled digest, AI reviews at start, during progress checks and on finish.
- [Short links](https://splithub.io/docs/links.md): Weighted and targeted destinations, sticky choice, UTM pass-through, click stats, QR codes.
- [Plans and limits](https://splithub.io/docs/pricing.md): Free, packs and Pro side by side, what counts toward the allowance (exposures, pageviews, events), what happens at the limit.

## Site

- [SplitHub: analytics and A/B testing in one install](https://splithub.io/)
- [Pricing](https://splithub.io/pricing)
- [Documentation](https://splithub.io/docs)
- [SplitHub compared to analytics and A/B testing tools](https://splithub.io/compare)
- [Free marketing tools](https://splithub.io/tools)
- [UTM generator](https://splithub.io/tools/utm-generator)
- [QR code generator](https://splithub.io/tools/qr-generator)
- [Slack emoji converter](https://splithub.io/tools/slack-emoji-converter)
- [Contact](https://splithub.io/contact)
- [Terms](https://splithub.io/terms)
- [Privacy](https://splithub.io/privacy)

## Packages

- splithub (CLI): https://www.npmjs.com/package/splithub
- @splithub/react, @splithub/next, @splithub/react-native, @splithub/core, @splithub/node, @splithub/stats, @splithub/adapter-sqlite, @splithub/adapter-d1, @splithub/mcp
- Native SDKs: Swift package SplitHub (iOS 14+, macOS 11+); Android io.splithub:splithub and io.splithub:splithub-compose (min SDK 21)
- Source: https://github.com/andreybo/splithub-ab-testing-platform
- Cloud API base URL: https://go.splithub.io (JSON, no envelope under /v1/*)
- Dashboard: https://app.splithub.io


---

<!-- https://splithub.io/docs/getting-started -->

# Getting started

SplitHub is analytics and experiments in one install, for websites and apps whose code is written with a coding agent. An analytics property counts pageviews (or app screens) and the events you send with `track()`; experiments (A/B, multivariate, redirect) are declared in `splithub.config.ts` or the dashboard, rendered with React, Next.js or React Native (or decided by a drop-in script; iOS and Android have native SDKs), and read from the CLI, the MCP server, the dashboard or an email. Events go to your own database or to SplitHub Cloud.

## One command

In the folder of your app:

```bash
npx splithub
```

The interactive menu covers experiments, analytics, short links, alerts, notes and allowed domains. On a new app, "Set up this app" walks through: sign in through a link (no key to paste), create or pick a cloud project, write `splithub.config.ts` and the framework files, print the provider integration snippet, install the agent skills and the MCP server entry, create the first experiment, push it. Analytics → Set up connects an analytics property. Every step is also a subcommand with flags and `--json`, which is what an agent uses:

```bash
npx splithub init --mode cloud --yes      # or --mode self for your own database
npx splithub analytics connect            # pick or create a property, name it on your provider
npx splithub create --kind value --id hero-title --variants control,bold \
  --value "control=Old headline" --value "bold=New headline" --goal signup --yes
npx splithub push
npx splithub results hero-title
```

Prefer to let the agent do it? Open the project in Claude Code, Cursor or Codex and say: *"Set up SplitHub analytics and A/B test the headline on the home page."* After `init` the agent has the [skills](/docs/agent-skills) and the [MCP server](/docs/mcp) it needs.

## What `init` writes

| File | Purpose |
|---|---|
| `splithub.config.ts` | Goals, analytics properties and experiments. The source of truth. |
| Provider snippet in the command output | Add it to `app/layout.tsx` or `main.tsx` to wrap the app in the provider. |
| `middleware.ts` (Next.js) | Visitor cookie, redirect experiments, header for Server Components. |
| `app/api/splithub/[[...path]]/route.ts` (self mode) | Ingest and results handler with a store. |
| `splithub/store.ts` (self mode, `--db postgres` or `mysql`) | A working store for your database. |
| `.claude/skills/*`, `.cursor/rules/splithub.mdc`, `AGENTS.md` or `CLAUDE.md` section | Agent skills. |
| `.mcp.json`, `.cursor/mcp.json` | MCP server registration (skip with `--no-mcp`). |
| `app/_layout.tsx` or `App.tsx` (React Native, Expo) | Wrapped in `<SplitHubProvider>` with `<ExpoRouterScreens />` or `<NavigationScreens />`. |

## In a mobile app

`init` notices React Native and Expo projects, installs `@splithub/react-native` and wraps the app entry with screen tracking. In an Xcode or Gradle project it prints the Swift package or Gradle line and a quick start instead: native apps take their experiments from SplitHub Cloud, so there is no config file to write. Start with [Apps](/docs/apps), then [React Native and Expo](/docs/react-native), [iOS](/docs/ios) or [Android](/docs/android).

## Turn on analytics

```bash
npx splithub analytics connect
```

It picks the project's property (or creates one; ids look like `sh-x1h78w`) and adds `property="sh-…"` to the `<SplitHubProvider>` in your code. In cloud mode the property is live at once, no push needed. From then on the provider sends a pageview on load and on every client-side navigation, and every `track(name, props?)` call is recorded as an event. Any event name works; nothing to declare first. Without the SDK, the `sh.js` tag with `data-property="sh-…"` does the same. See [Analytics](/docs/analytics) and [Reports](/docs/analytics-reports).

## Render a variant

```tsx
import { useValue, useTrack } from '@splithub/react';

export function Hero() {
  const title = useValue<string>('hero-title');
  const track = useTrack();
  return <h1 onClick={() => track('signup')}>{title}</h1>;
}
```

The experiment's goal can be any event your app sends with `track()`: the same call feeds the analytics property and the experiments that measure it, one row per action.

`create` writes the experiment as `running`: it goes live for every visitor when you deploy the code that renders it. Check it locally first with `?sh_force=<id>:<variant>`; development never sends events to the cloud. To hold an experiment, create it with `--status draft` and start it later with `npx splithub start <id>`, or pause it in the dashboard.

A `value` experiment changes data (text, a URL, a number, JSON) without new components. A `component` experiment renders different JSX per variant with `<Experiment id="…"><Variant name="control">…</Variant></Experiment>`. A `redirect` experiment sends each variant to its own page. An `mvt` experiment changes several things at once and reads each one on its own. See [React](/docs/react), [Next.js](/docs/nextjs), [Redirect experiments](/docs/redirect-experiments) and [splithub.config.ts](/docs/config).

## Read the verdict

```bash
npx splithub status            # every experiment: status, visitors, days, verdict headline; in the cloud also each property's last 7 days
npx splithub results hero-title
```

In SplitHub Cloud the verdict is one of `no_data`, `insufficient_sample`, `srm_detected`, `winner_found`, `no_significant_difference`, `guardrail_breached`, with a message and the numbers behind it: visitors and conversions per variant, relative lift, an always-valid p-value and confidence interval, probability to beat, sample quality and a data-quality score of 0 to 5 stars. The test is safe to check any time. The [statistics page](/docs/statistics) explains each part. A self-hosted endpoint answers the raw numbers (visitors, conversions, rate, revenue per variant); verdicts come with SplitHub Cloud.

How many visitors will it take? `npx splithub plan --baseline 0.05 --mde 0.1` answers before you start, no account needed.

## Finish

```bash
npx splithub finish hero-title
npx splithub ship hero-title --keep bold --dry-run   # then without --dry-run
```

`ship` finishes the experiment, removes it from the config and rewrites the code to the kept variant; `--dry-run` shows the diff first. In cloud mode a finished experiment stops accepting events at the edge; nothing more is stored or billed.

## Next

- [How it works](/docs/concepts) explains properties, assignment, exposures, events and goals.
- [splithub.config.ts](/docs/config) lists every option.
- [Self-hosted](/docs/self-hosted) if the events must stay in your database.
- [SplitHub Cloud](/docs/cloud) for the dashboard, reports, live overrides, alerts and AI reviews.


---

<!-- https://splithub.io/docs/concepts -->

# How it works

Five ideas explain the whole system.

## The config file is the source of truth

`splithub.config.ts` declares goals, analytics properties and experiments. It is committed, reviewed and diffed like the rest of the code. The CLI edits it (`create`, `start`, `pause`, `finish`, `ship`, `analytics create`), the SDK reads it, and in cloud mode `push` uploads a normalized copy so the dashboard and the API can read the same thing.

The dashboard never edits the file. Experiments it creates are "cloud-only" until `npx splithub pull` writes them into the file; experiments the file owns are read-only in the dashboard except for pausing and finishing. Live overrides (status, traffic, weights, `value` payloads) sit on top of the config. The browser SDK applies them from a first visit on: it waits briefly for them when nothing is cached and refreshes them in the background on later pages. It never changes a variant a page has shown.

Apps are the exception. A config built into an app binary only changes with a store release, so app experiments start and change in the dashboard, and installed apps pick them up on their next launch. Native iOS and Android apps have no config file at all. See [Apps](/docs/apps).

## Properties and experiments

An **analytics property** is a stream of pageviews and events, like a site in a web analytics tool: visitors, visits, pages, sources, events, goal conversions, funnels and retention. It has no variants and no verdicts; its reports are counts. Declare it under `properties` in the config, or make it in the dashboard; ids look like `sh-x1h78w`. Events go only to a property named explicitly: `property` on the provider or client, `data-property` on `sh.js`.

An **experiment** splits visitors between variants and compares one goal. Both share one install, one visitor id and one `track()` call: with a property on the provider, each `track()` sends one event row and each page one page row, and the experiments whose goal is that event or page count them from those rows. Nothing extra is sent or billed. See [Analytics](/docs/analytics).

## Assignment is a local hash

A visitor gets a random id in the `sh_vid` cookie (first party, set by the SDK or the Next.js middleware). Assignment uses MurmurHash3 with the visitor id, experiment key and seed, then selects from the cumulative variant weights. A separate hash controls entry into the traffic share; a holdout and layers, when you use them, are checked before that. Given the same config and targeting context, browser, edge and server agree. Bucketing is local; fetching cloud overrides or hosted script config may require a request. Crawlers see the control and are never counted.

Consequences: changing `seed` reshuffles every visitor (never do it on a running experiment); changing `traffic` does not; a visitor keeps the same variant across pages and sessions in the same browser, while the id and experiment settings remain unchanged.

## Exposures, events and goals

An **exposure** is "this visitor saw this experiment in this variant". The SDK records it when the variant is actually rendered (`<Experiment>` mounts, `useValue` is read, the redirect fires).

An **event** is anything your app sends with `track(name, props?)`. Any name is recorded; nothing to declare first. A **goal** is an event marked as one: in `goals` in the config, with the goal switch on an event in the dashboard, or simply by naming the event as an experiment's goal (`Video Played` becomes the goal `video-played`). A page visit (`pageview` with a path) or a click on a selector can be a goal too.

In SplitHub Cloud attribution is decided at ingest:

- a visitor counts once per experiment, in the variant of their **first exposure**; a returning visitor is not stored or billed again;
- a goal converts the experiments that measure it when it arrives **at or after** that exposure; earlier goals count for nothing;
- units are **unique visitors**, not hits; at most 50 of one goal per visitor per day are kept;
- goals from visitors who never saw an experiment do not reach any experiment (an analytics property still records the event).

Self-hosted stores apply the same rule when they read. In the cloud, exposures of running experiments, pageviews and custom events are billed; goal rows never are. Exposures for paused, finished or draft experiments are dropped at the edge and not stored.

## Self-hosted or cloud

| | Self-hosted | SplitHub Cloud |
|---|---|---|
| Where events go | your database through a `Store` (SQLite, D1, Postgres, MySQL, custom) | `https://go.splithub.io` |
| Config line | `storage: { mode: 'self', endpoint: '/api/splithub' }` | `storage: { mode: 'cloud', key: 'pk_…' }` |
| Experiment results | raw numbers per variant: visitors, conversions, rate, revenue | verdicts, p-values, stars, guardrails, factor effects, SRM, breakdowns |
| Analytics | raw counts: pageviews, visitors, visits, events by name | reports: pages, sources, channels, funnels, paths, retention, realtime |
| Where you read it | CLI and MCP against your app's endpoint | CLI, MCP, dashboard, email |
| Live overrides | no (edit the file) | yes |
| Price | free, unlimited | 50,000 visitors (exposures, pageviews and events) per project per month free, then packs or Pro |

The SDK, the CLI and the MCP server are the same in both modes. The analysis (verdicts, stars, guardrails, factor effects, breakdown comparisons, AI reviews) runs only in SplitHub Cloud; a self-hosted endpoint answers with `analysis: { available: false }` next to its numbers. To switch, update `storage` and configure the destination: a handler and database for self-hosting, or a project, keys and config push for cloud.

## Vocabulary

- **property**: an analytics stream of pageviews and events, read as reports.
- **experiment**: one question with 2+ variants; `kind` is `value`, `component`, `redirect` or `mvt`.
- **control**: the first declared variant, what exists today.
- **weight**: relative share of traffic per variant (50/50, 1/1, 90/10).
- **traffic**: share of visitors who enter the experiment at all (`0.5` = half; the rest see the control and record no exposure).
- **conversion**: a visitor who reached the goal, counted once.
- **verdict**: the one-line conclusion of the statistics, with its status code.
- **SRM**: sample ratio mismatch, the split you got differs from the one you configured; the setup is broken.
- **guardrail**: a goal that must not get worse; a variant that hurts one is never the winner.


---

<!-- https://splithub.io/docs/config -->

# splithub.config.ts

The config is a plain TypeScript (or JavaScript) module that exports `defineConfig(...)` from `@splithub/core`. `defineConfig` validates and normalizes it at import time, so mistakes fail fast with a readable message. The file ships to the browser: never put secrets in it.

```ts
import { defineConfig } from '@splithub/core';

export default defineConfig({
  project: 'my-app',
  storage: { mode: 'cloud', key: 'pk_live_…' },
  runDraftsInDev: true,
  goals: {
    signup: { type: 'event', name: 'Sign up' },
    purchase: { type: 'event', revenue: true },
    'video-played': { type: 'event', event: 'Video Played', value: 2 },
    pricing_view: { type: 'pageview', path: '/pricing' },
    cta_click: { type: 'click', selector: '#cta' },
  },
  properties: {
    'sh-x1h78w': { name: 'Marketing site' },
  },
  layers: { checkout: {} },
  holdout: { percent: 5, goal: 'purchase' },
  experiments: {
    'hero-title': {
      kind: 'value',
      status: 'running',
      goal: 'signup',
      name: 'Hero headline',
      description: 'Feature-led vs outcome-led headline',
      metrics: { secondary: ['pricing_view'], guardrails: ['purchase'] },
      variants: {
        control: { weight: 50, value: 'Ship experiments from your terminal' },
        outcome: { weight: 50, value: 'Know which version wins, by Friday' },
      },
    },
    'pricing-cta': {
      kind: 'component',
      status: 'draft',
      goal: 'purchase',
      traffic: 0.5,
      variants: { control: 1, 'see-plans': 1, 'talk-to-us': 1 },
      maxExposures: 20000,
      layer: { key: 'checkout', range: [0, 50] },
      schedule: { startAt: '2026-11-01T00:00:00Z', endAt: '2026-11-30T00:00:00Z' },
    },
    'hero-combo': {
      kind: 'mvt',
      status: 'running',
      goal: 'signup',
      factors: {
        headline: { old: 'Ship experiments', new: 'Know what wins' },
        button: { blue: '#2563eb', green: '#16a34a' },
      },
    },
    'landing': {
      kind: 'redirect',
      status: 'running',
      goal: 'signup',
      match: '/',
      variants: { control: { weight: 50, to: '/' }, 'new-landing': { weight: 50, to: '/start' } },
    },
  },
});
```

## Top level

| Field | Required | Meaning |
|---|---|---|
| `project` | yes | Name shown in the CLI and the dashboard. |
| `storage` | yes | `{ mode: 'self', endpoint }` or `{ mode: 'cloud', key, endpoint? }`. |
| `goals` | no | Map of goal key → goal. |
| `properties` | no | Map of property id → analytics property. |
| `experiments` | yes | Map of experiment key → experiment. |
| `layers` | no | Map of layer key → `{ seed? }`, for experiments that must never share a visitor. |
| `holdout` | no | `{ percent, seed?, goal? }`: a share of visitors kept out of every experiment. |
| `visitorKey` | no | Cookie name for the visitor id, default `sh_vid`. |
| `runDraftsInDev` | no | `true` serves `draft` experiments like running ones while the app runs in development. Default `false`. |

`storage.endpoint` in self mode is the path (or URL) where the `@splithub/node` handler is mounted. In cloud mode `key` is the project's public key; `endpoint` defaults to `https://go.splithub.io/v1/events` and only changes for a self-hosted cloud or staging.

## Drafts in development

A `draft` experiment is invisible to visitors: everyone sees the control and nothing is recorded. To see it in your own app before you start it, set `runDraftsInDev: true`. While `NODE_ENV` is `development` (`next dev`, `vite`), drafts behave exactly like running experiments: variants by visitor, targeting, redirects, exposures and goals. A production build ignores them as before, so the same config is safe to deploy.

In development the schedule of a draft is ignored, so an experiment that starts next week can be checked today. In cloud mode development never sends events to the cloud, for drafts and running experiments alike, so your own visits never reach the results and nothing is billed. Deployed builds, and `vite preview`, send as usual. While nothing in the project is running (no experiment, no property) the SDK holds events back too, because the cloud would drop them.

In development the SDK also explains itself, one line per experiment: a draft that everyone sees as the control, a draft shown because of this option and which variant you got, a paused experiment, events held back. Next.js server code prints it in the terminal that runs `next dev`. In a Vite app the SDK runs in the browser, so add the plugin to see it in the terminal that runs `vite`:

```ts
// vite.config.ts
import { splithub } from '@splithub/core/vite';

export default defineConfig({ plugins: [react(), splithub()] });
```

On start and on every save of the config it prints each experiment and what it does in development, then forwards the SDK's notes from the browser. Without the plugin the notes stay in the browser console. Production builds print nothing. With `?sh_debug=1` the debug panel shows such assignments with the reason `dev`; its "new visitor" button lets you walk through every variant. `npx splithub init` turns the option on for new projects.

## Goals

A goal is an event marked as one. You do not have to declare event goals: an experiment's `goal` (or a metric) may name any event, and a name that is not in `goals` becomes an event goal keyed by its slug (`Video Played` → `video-played`, with `event: 'Video Played'`). Declare a goal when you want a label, a value, revenue, a page visit or a click.

| Type | Fields | Fires when |
|---|---|---|
| `event` | `revenue?: boolean`, `event?: string` | your code calls `track('<key>', props?)`, or `track('<event>')` when `event` is set; with `revenue: true` the `props.revenue` number is summed per variant |
| `pageview` | `path` | a page with that path is viewed (exact match, or prefix with a trailing `*`) |
| `click` | `selector` | an element matching the CSS selector is clicked (the SDK and the drop-in script bind it) |

Every goal also takes `name` (a label for people; the key stays what the code sends), `description`, and `value` (what one conversion is worth in analytics reports when the event carries no `revenue` prop). `event` names the event when it is not a valid key, like `'Video Played'` for `video-played`. Goals count as conversions in every analytics property unless a property's `goals` narrows them. Goals created in the dashboard reach cloud clients; add their definitions to the local file yourself, `pull` adopts experiments, not goals.

## Properties

```ts
properties: {
  'sh-x1h78w': { name: 'Marketing site', goals: ['signup', 'purchase'] },
}
```

| Field | Default | Meaning |
|---|---|---|
| `name` | the id | shown in the dashboard and the CLI (up to 80 characters) |
| `status` | `running` | `running` or `paused`; a paused property's events are dropped at ingest |
| `goals` | every goal | goal keys this property reports as conversions |
| `description` | none | free-form note |
| `kind` | `site` | `site` or `app` (screens, versions, retention; see [Apps](/docs/apps)) |

`npx splithub analytics create --name "Marketing site"` or `analytics connect` writes the entry with a generated id and, in cloud mode, creates it in the cloud at once. Properties made in the dashboard need no entry in the file. See [Analytics](/docs/analytics).

## Experiments

Keys are lowercase `a-z 0-9 - _`, 1–64 characters, and start with a letter or digit. The **first variant is the control**.

| Field | Default | Meaning |
|---|---|---|
| `kind` | required | `value`, `component`, `redirect` or `mvt` |
| `status` | required | `draft`, `running`, `paused`, `finished` |
| `variants` | required (not for `mvt`) | see below |
| `factors` | required for `mvt` | factor → level → value, see below |
| `goal` | none | the goal the verdict is computed on: a key from `goals` or any event name |
| `metrics` | none | `{ secondary?: [goal], guardrails?: [goal \| { goal, worse: 'higher' }] }`, read beside the primary goal |
| `traffic` | `1` | share of visitors (0–1) entering the experiment; others see the control without an exposure |
| `seed` | the key | hash seed; never change it on a running experiment |
| `name` | the key | human name shown in the dashboard and the CLI (up to 80 characters); rename it freely, the key and the data stay |
| `description` | none | shown in the dashboard and in emails |
| `match` | required for `redirect` | path the redirect applies to (exact, or prefix with trailing `*`) |
| `maxExposures` | none | the cloud finishes the experiment when stored exposure events reach this number |
| `schedule` | none | `{ startAt?, endAt? }` ISO dates; outside the window the control is served and nothing is recorded |
| `layer` | none | `{ key, range: [start, end] }`: the buckets 0–99 of a declared layer this experiment enrolls, end excluded |
| `minDays` | `0` | opt-in minimum runtime in days before a verdict, whole number 0–30 |
| `goodSample` | `5000` | total visitors at which the sample counts as good, 100–10,000,000; informational |
| `flow` | none | targeting graph, see [Targeting flows](/docs/targeting) |

### Variants by kind

```ts
// component: weights only, JSX lives in the app
variants: { control: 1, bold: 1 }

// value: weight + payload (string, number, boolean, object, array)
variants: { control: { weight: 50, value: 'Old' }, bold: { weight: 50, value: 'New' } }

// redirect: weight + destination
variants: { control: { weight: 50, to: '/' }, v2: { weight: 50, to: '/home-v2' } }
```

Weights are relative: `{ a: 1, b: 1 }` and `{ a: 50, b: 50 }` are the same split; `{ a: 90, b: 10 }` is a 90/10 split.

### Multivariate (`mvt`)

```ts
factors: {
  headline: { old: 'Ship experiments', new: 'Know what wins' },
  button: { blue: '#2563eb', green: '#16a34a' },
}
```

Every combination becomes a variant with an equal weight: `old-blue`, `old-green`, `new-blue`, `new-green`. The combination of every factor's first level is the control. `useValue('hero-combo')` returns the combination's values, `{ headline, button }`. At most 4 factors, 4 levels each and 16 combinations. Results show the combinations and, below them, each factor read on its own. Every combination needs the minimum sample by itself, so an `mvt` experiment needs more traffic than a two-variant one. The CLI writes `factors`, never the derived variants.

### Metrics and guardrails

`secondary` goals are compared with the control the same way as the primary goal, for information. A `guardrail` must not get significantly worse: a variant that hurts one is never called the winner, and the verdict becomes `guardrail_breached`. A guardrail is worse when its conversion rate drops; use `{ goal: 'refunds', worse: 'higher' }` for goals where more is bad. In the cloud, metric goals are counted from the moment they are pushed, with no backfill. See [Statistics](/docs/statistics).

### Layers and holdout

```ts
layers: { checkout: {} },
experiments: {
  'checkout-steps': { /* … */ layer: { key: 'checkout', range: [0, 50] } },
  'checkout-copy':  { /* … */ layer: { key: 'checkout', range: [50, 100] } },
}
```

Experiments in one layer never share a visitor. Each visitor falls in one bucket 0–99 per layer, the same for every experiment of that layer, and an experiment enrolls only the buckets in its range. Ranges are explicit, so adding an experiment never moves the visitors of another. Overlapping ranges of unfinished experiments in one layer fail `defineConfig`. A visitor outside the range sees the control without an exposure. `seed` on the layer reshuffles its buckets.

`holdout: { percent: 5 }` keeps that share of visitors (at most 50) on the control in every experiment, with no exposures. Everyone who reaches a running experiment is counted in the reserved comparison `__holdout` (`holdout` against `enrolled`), which measures the long-term effect of all your experiments together. `goal` is its primary goal (any event name; default: the first declared goal); the other goals are read as secondary metrics. `npx splithub holdout set 5 [--goal purchase]` writes it, `holdout off` removes it.

Holdout and layers are checked before traffic and the targeting flow, identically in the SDK, the Next.js middleware and the drop-in script.

## What the CLI changes

`create` adds an experiment (with `--factor`, `--secondary`, `--guardrail`, `--layer`, `--min-days`, `--good-sample`), `start`/`pause`/`finish` change `status`, `ship` and `remove` take an experiment out, `holdout` sets the holdout, `analytics create` and `analytics connect` add a property, `pull` adds missing dashboard-created experiments (including flows) but not goal definitions, `init` writes the file the first time. Edits keep your formatting where possible; the file stays a normal TypeScript module you can edit by hand.

## Rules

- Never change `seed`, `variants` or weights of a running experiment; create a new one.
- Never reuse the key of an earlier experiment: the key is its id for good.
- Keep one `id` for things that must change together, separate ids for independent questions.
- On low traffic run at most 2–3 experiments per page.
- Keys that exist in the file are owned by the file: the dashboard cannot edit them (it can pause or finish them).
- In cloud mode a status set in the dashboard wins over the file's `status`, from a visitor's first page, until you clear it. The dashboard shows both when they differ.


---

<!-- https://splithub.io/docs/analytics -->

# Analytics

An analytics property is a stream of pageviews and custom events, like a site in Google Analytics. It lives next to your experiments: the same config file, the same SDK or script, the same CLI and key, and the same storage choice (SplitHub Cloud or your own database). A property has no variants and no verdicts; its reports are counts. How to read them: [Reports](/docs/analytics-reports).

## Properties

Each property has a generated id like `sh-x1h78w`. Events go only to a property named by its id, never to a guess, so a page without a property sends no analytics at all.

A property comes from one of two places:

- **The config file.** Self-hosted projects keep their properties here; cloud projects may too.

  ```ts
  // splithub.config.ts
  properties: {
    'sh-x1h78w': { name: 'Marketing site' },
  },
  ```

  | Field | Default | Meaning |
  |---|---|---|
  | `name` | — | shown in the dashboard and the CLI, up to 80 characters |
  | `description` | — | a note for your team |
  | `status` | `running` | `running` or `paused` |
  | `goals` | every goal | goal keys counted as conversions in this property |
  | `kind` | `site` | `site` for a website, `app` for a mobile or desktop app (screens, versions, retention; see [Apps](/docs/apps)) |

- **The dashboard** (Analytics → New property). Its id is on the property's page. It needs no push and no change to the file.

## Set it up

One command picks the project's property (or creates one) and adds it to the provider in your code:

```bash
npx splithub analytics connect                          # or: Analytics → Set up in the npx splithub menu
npx splithub analytics connect --name "Marketing site"  # create one with this name
npx splithub analytics connect sh-x1h78w                # use this id
```

It finds the one `<SplitHubProvider>` or `<SplitHubNextProvider>` in your code and adds `property="sh-…"`. When there is none, or several, it prints the snippet to add yourself. In cloud mode the property is created in the cloud at once, so the next deploy collects: no `push` needed. To only write the property into the file, use `npx splithub analytics create --name "Marketing site"`. In a React Native or Expo project the property is made as an app property (`kind: 'app'`), and screens take the place of pages.

Never `push` just to add analytics. A push uploads the whole file, and an experiment the cloud knows from an earlier push that the file lacks would be removed (`push --dry-run` lists what would change).

### React and Vite

```tsx
<SplitHubProvider config={config} property="sh-x1h78w">
  <App />
</SplitHubProvider>
```

Details: [React](/docs/react#analytics).

### Next.js

```tsx
<SplitHubNextProvider config={config} property="sh-x1h78w" visitorId={sh.visitorId ?? undefined} remoteOverrides={sh.overrides}>
  {children}
</SplitHubNextProvider>
```

Details: [Next.js](/docs/nextjs#analytics).

### Any site, no build step

```html
<script src="https://go.splithub.io/sh.js" data-key="pk_live_…" data-property="sh-x1h78w" async></script>
```

Details: [Drop-in script](/docs/script#analytics).

## Pageviews

With a property, a pageview is recorded on load and on every client-side navigation: `history.pushState`, `replaceState`, back and forward, and hash routes. A new path, query or hash is a new page. You do not call anything for a single-page app. Each page also reports time on page and scroll depth, which the reports turn into visit duration and engagement.

Turn the automatic navigation tracking off with `trackNavigation: false` on the provider (or `createClient`) and report pages yourself with `usePageview(path)` or `client.pageview(path)`.

## Events

`track` is the one call for events, in every install:

```tsx
const track = useTrack();                    // React and Next.js
track('Video Played', { id: 3 });
track('checkout', { revenue: 49 });
```

```js
splithub.track('Video Played', { id: 3 });   // sh.js
```

- **Names**: letters, digits, spaces and `_ . : / -`, up to 64 characters. Any name is recorded; there is nothing to declare first.
- **Props**: a flat object of up to 4 KB of JSON. Larger props keep `revenue` and the plain values that fit, with a console warning.
- `revenue` is the one prop with a built-in meaning: it becomes the revenue of a goal.
- Only what your code passes to `track()` is sent. Fire events on actions, never in a render loop or on every scroll: each one is stored and billed.

## Identify

After sign-in, tie the visitor to your own user id:

```tsx
const identify = useIdentify();
identify(user.id, { plan: 'pro' });   // after sign-in
identify(null);                       // on sign-out
```

`splithub.identify(id, traits)` does the same from sh.js. The id is 1 to 128 characters; traits are flat text, number and true/false values up to 4 KB. The browser remembers the id and sends it again once per session. Reports then count `users` next to visitors, and you can break any report down by a trait (`--by trait --key plan`). Use an internal id, never an email or a name.

## Events and goals

Every event is recorded. A **goal** is an event you marked as one:

- a goal in `goals` of the config (see [Goals and revenue](/docs/goals)),
- the goal switch on an event in the dashboard (Settings → Events), or
- naming the event as an experiment's goal: `Video Played` becomes the goal `video-played`.

Goals count as conversions in every property unless the property's `goals` list narrows them. A goal's `value` is what one conversion is worth when the event carries no `revenue` prop; `event: 'Video Played'` maps a goal key to an event name that is not a valid key.

## One install for analytics and experiments

The provider (or sh.js) with a `property` collects pageviews and runs experiments. Each `track()` sends one event row and each page one page row. Experiments whose goal is that event or that page count their conversions from those same rows, so nothing extra is sent or billed.

Keep one install per property. If sh.js and the SDK both run on a page for the same property, the first one to send a page collects pageviews, time on page and identify; the other sends only its own `track()` calls.

## Development

A development build (`NODE_ENV=development`) sends nothing to SplitHub Cloud, so your own visits never reach the reports. The console says so once, and `?sh_debug=1` logs each row held back. Check tracking on a deploy or with `vite preview`, then list the latest raw rows:

```bash
npx splithub analytics events sh-x1h78w
```

## Allowed domains

Allowed domains are set per property, like per experiment. An empty list accepts every origin.

```bash
npx splithub domains set property sh-x1h78w example.com   # subdomains included
npx splithub domains clear property sh-x1h78w             # any origin again
npx splithub domains                                      # every list
```

Pageviews and events from another origin are dropped; a batch with nothing allowed answers `403`. Add `localhost` when you test against the cloud from it. An app sends no web origin, so its app id stands in: add `com.acme.shop` to the list (exact match). A list with only websites refuses apps.

## Pause, archive, remove

```bash
npx splithub analytics pause sh-x1h78w      # stop collecting; resume with: analytics resume sh-x1h78w
npx splithub analytics archive sh-x1h78w    # stop collecting and leave the list, numbers kept
npx splithub analytics restore sh-x1h78w    # back in the list, paused
npx splithub analytics remove sh-x1h78w     # out of the config
```

Pause and resume take effect in the cloud within a minute; events of a paused property are dropped and not billed. Archive and restore are SplitHub Cloud features, the same as Archive in the dashboard. `remove` takes a property out of the file (push next); removing a property made in the dashboard deletes it with its numbers.

## What is billed

Every pageview and every custom event of a running property counts like one exposure against the project's allowance. Time on page, scroll depth and identify are not billed, and neither are the goal conversions experiments count from your events. See [Plans and limits](/docs/pricing).

## Privacy

- Bots are never counted: known crawlers are turned away at the edge and bot user agents never reach analytics.
- Keep personal data out of props and traits: no emails, names or ids from other systems.
- The visitor id is a random first-party cookie (`sh_vid`), or a random id in the app's own storage; identify links it to your user id only when you call it.

## Self-hosted

With `storage: { mode: 'self' }` the rows go to your own database through the [ingest handler](/docs/self-hosted#analytics). The same commands answer raw counts for a range of UTC days: pageviews, visitors, visits, identified users and events by name.

```bash
npx splithub analytics sh-x1h78w --days 7
npx splithub analytics sh-x1h78w --from 2026-10-01 --to 2026-10-31
```

Reports with pages, sources, channels, visits, conversions, filters, `--by` and `--compare`, plus funnels, paths and retention, come with SplitHub Cloud.


---

<!-- https://splithub.io/docs/analytics-reports -->

# Reports

Everything an [analytics property](/docs/analytics) collects can be read in three places: the dashboard, the `splithub` CLI and the MCP server. They answer from the same reports, so an agent and a teammate looking at the dashboard see the same numbers. Reports are counts, not experiment results: for a verdict use `npx splithub results`.

Reports with dimensions, filters, visits and conversions are SplitHub Cloud features. A self-hosted property answers raw counts (see [Self-hosted](/docs/analytics#self-hosted)).

## Where to read them

| Report | Dashboard (property page) | CLI | MCP tool |
|---|---|---|---|
| Every property, last 30 days | Analytics | `npx splithub analytics` | `splithub_analytics` |
| Totals, goals, top pages and sources | Overview | `analytics <id>` | `splithub_analytics` with `property` |
| By a dimension | Pages, Sources, Audience, Events & goals | `analytics <id> --by <dimension>` | `splithub_analytics` with `by` |
| Funnels | Funnels | `analytics funnel <id>` | `splithub_analytics_funnel` |
| Paths | Paths | `analytics paths <id>` | `splithub_analytics_paths` |
| Retention | Retention | `analytics retention <id>` | `splithub_analytics_retention` |
| Right now | Realtime | `analytics realtime <id>` | `splithub_analytics_realtime` |
| Latest raw rows | Raw events | `analytics events <id>` | `splithub_analytics_events` |
| Event props | Events & goals | `analytics props <id> --event <name>` | — |
| CSV | Export | `analytics export <id>` | — |
| Notes | Notes | `npx splithub notes` | `splithub_notes` |
| Saved segments | the filter bar | `analytics segments` | `splithub_segments` |

Every CLI command takes `--json`. `npx splithub status` also lists each property's last 7 days against the 7 before, and `npx splithub report` adds them as an Analytics table.

## Totals

```bash
npx splithub analytics sh-x1h78w --days 7
npx splithub analytics sh-x1h78w --from 2026-10-01 --to 2026-10-31
```

Visitors, new visitors, identified users, visits, pageviews, events, bounce rate and visit duration, then each goal (conversions, completions, revenue), the top pages, the top sources and the notes in the range. The default range is the last 30 days; one report covers at most 400 days. Days follow the project's time zone (Settings).

## Dimensions

`--by` groups the report by one dimension:

| Group | Dimensions |
|---|---|
| Pages | `page`, `entry`, `exit` |
| Sources | `source`, `referrer`, `channel`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |
| Audience | `country`, `region`, `city`, `device`, `os`, `browser`, `language`, `host` |
| Apps | `platform` (`ios`, `android`, `web`…), `app_version` |
| Actions | `event`, `goal` |
| Your data | `trait --key plan` (an identify trait), `variant --experiment hero` (the variant each visitor saw) |

```bash
npx splithub analytics sh-x1h78w --by channel
npx splithub analytics sh-x1h78w --by source --goal signup     # conversions of signup per source
npx splithub analytics sh-x1h78w --by variant --experiment hero
npx splithub analytics sh-x1h78w --by trait --key plan
```

With a visit dimension, `--goal <key>` adds that goal's conversions per row.

## Filters

`--filter dimension=value[,value]` narrows the visits a report starts from. Repeat it to combine filters; several values of one filter mean any of them.

```bash
npx splithub analytics sh-x1h78w --by page --filter country=DE,FR --filter source="(none)"
```

Any visit dimension, `page` and `event` filter this way. Four prefixes reach your own data:

| Filter | Keeps visits |
|---|---|
| `p.gclid=abc` | whose landing page had that query parameter |
| `t.plan=pro` | of users with that identify trait |
| `e.signup.plan=pro` | that sent the event `signup` with that prop value |
| `x.hero=bold` | of visitors who saw that variant of the experiment |

## Compare

```bash
npx splithub analytics sh-x1h78w --days 7 --compare                      # the 7 days right before
npx splithub analytics sh-x1h78w --days 7 --compare year                 # the same days a year earlier
npx splithub analytics sh-x1h78w --compare 2026-08-01..2026-08-31        # days you choose
```

The answer gains `previous`, and the CLI prints the change per row.

## Segments

A segment is a saved set of filters that every report can apply.

```bash
npx splithub analytics segments --save "German traffic" country=DE
npx splithub analytics sh-x1h78w --segment "German traffic" --by page
npx splithub analytics segments                                   # the list
npx splithub analytics segments --delete "German traffic"
```

`--property <id>` keeps a segment to one property. A `--filter` on the same dimension wins over the segment's.

## Funnels

```bash
npx splithub analytics funnel sh-x1h78w --steps "page:/,event:Signup,goal:paid"
npx splithub analytics funnel sh-x1h78w --steps "page:/pricing,goal:paid" --within 7d --by country
```

Two to eight steps: `page:/path` (patterns like `page:/blog/*` work), `event:<name>` or `goal:<key>`. Visitors count for a step only after the steps before it. `--within` is `visit` (the default, all in one visit), `7d` or `30d` from the first step. Each step answers `visitors`, `conversion` (share of step 1) and `dropoff` (share lost since the step before).

## Paths

```bash
npx splithub analytics paths sh-x1h78w --page /pricing           # where visits went next
npx splithub analytics paths sh-x1h78w --page /pricing --prev    # where they came from
```

Rows are pages with their visits; `(exit)` means the visit ended there, `(entrance)` that it started on the page.

## Retention

```bash
npx splithub analytics retention sh-x1h78w
npx splithub analytics retention sh-x1h78w --start event:Signup --return visit --period day
```

Visitors are grouped by the day or week they started (`--start visit`, `event:<name>` or `goal:<key>`), and each cohort shows how many came back (`--return visit` or `event:<name>`) in each period after. The default is visit to visit, by week.

With `--json` the answer is `cohorts[] { start, users, retained[] }`: `retained[0]` is the cohort period itself, `retained[n] / users` the share back in period n. One report covers up to 90 days or 26 weeks (`clamped: true` when cut). For an app this is the report to watch; screens count as visits like pages do (see [Apps](/docs/apps)).

## Realtime

```bash
npx splithub analytics realtime sh-x1h78w
```

Visitors in the last 5 minutes, pageviews and events per minute over the last 30 minutes, top pages and sources. The quickest check that tracking works after a deploy.

## Event props

```bash
npx splithub analytics props sh-x1h78w --event Signup             # the prop names of Signup
npx splithub analytics props sh-x1h78w --event Signup --key plan  # the values of one prop
```

## Export

```bash
npx splithub analytics export sh-x1h78w --by day > daily.csv
npx splithub analytics export sh-x1h78w --by page > pages.csv
npx splithub analytics export sh-x1h78w --raw > events.csv
```

CSV to stdout, for the range and filters you pass. `--raw` exports the raw tail (see [Retention](/docs/cloud#retention)).

## Notes

A note marks a day on every chart, so a jump in traffic has its reason next to it.

```bash
npx splithub notes add "Launched new pricing" --kind win --property sh-x1h78w --day 2026-10-05
npx splithub notes --property sh-x1h78w
```

Add one whenever you ship something that may move traffic.

## Alerts

Alerts on a property are a Pro feature, set in the dashboard (Alerts) or with the CLI:

```bash
npx splithub alerts add traffic_drop --property sh-x1h78w --percent 50
npx splithub alerts add traffic_spike --property sh-x1h78w --percent 50
npx splithub alerts add goal_silent --property sh-x1h78w --goal signup --hours 24
npx splithub alerts add event_count --property sh-x1h78w --event Signup --count 1000 --repeat
```

The digest covers properties too: visitors, top sources and pages, goals and events against the period before. Channels and schedules: [Alerts, digest, AI reviews](/docs/alerts).

## Words

| Word | Meaning |
|---|---|
| visitor | one browser, by its `sh_vid` cookie |
| user | a visitor you identified with `identify()` |
| visit | a run of pageviews and events that ends after 30 minutes without any (`sessions` in JSON) |
| bounce | a visit with one page and no event; bounce rate is bounces divided by visits |
| duration | time in a visit, in milliseconds in JSON |
| source | the UTM source, or the referrer's site (Google, Facebook…); `(none)` is direct |
| channel | sources grouped: Direct, Organic Search, Paid Search, Organic Social, Paid Social, Email, Referral, Affiliate, Other |
| entry, exit | the first and the last page of a visit |
| conversion | a visitor reaching a goal, counted once per visitor in the range |
| completions | how many times the goal happened |

Bots are never counted.

## For agents

The [analytics skill](/docs/agent-skills) that `npx splithub skills` installs teaches an agent these commands. Ask it in plain words ("where did signups come from last week?", "how many visitors reach checkout from pricing?") and it picks the report, the range and the filters, and quotes the counts as they are.


---

<!-- https://splithub.io/docs/redirect-experiments -->

# Redirect experiments

A redirect experiment tests whole pages: visitors who match a path are sent to a different URL per variant. No component code is involved, so it works for a redesign, a new landing page, a different checkout flow, or two pages built in a no-code tool.

```ts
'landing': {
  kind: 'redirect',
  status: 'running',
  goal: 'signup',
  match: '/',
  variants: {
    control: { weight: 50, to: '/' },
    'new-landing': { weight: 50, to: '/start' },
  },
}
```

`match` is a path, exact or a prefix with a trailing `*` (`/pricing*`). `to` is the destination per variant; the control usually points at the matched page itself. Use same-site paths for Next.js middleware rewrites. The drop-in script and short links can navigate to absolute URLs on another host.

## Three ways to serve it

| Where | How | Flash |
|---|---|---|
| Next.js | `splithubMiddleware` rewrites the request at the edge; the address bar keeps the original URL | none |
| Drop-in script | `sh.js` assigns and navigates; put `<meta name="splithub-experiment" content="landing">` before the script | rendering held for up to 1,500 ms by default |
| Short links | a SplitHub link with two weighted destinations (no config needed) | a 302, like any short link |

The middleware and the script decide the same way as the SDK: same hash, same targeting flow, and the [holdout and layers](/docs/config) checked first. A held-out visitor, or one outside the experiment's layer range, gets the control and records no exposure; every visitor who reaches a running redirect experiment still counts in the holdout comparison.

A draft redirect is served in development when the config has `runDraftsInDev: true`, by the middleware and by the script alike. `?sh_force=landing:new-landing` previews one destination of a running experiment.

## Creating one

From the CLI: `npx splithub create --kind redirect --id landing --variants control,new-landing --match / --to control=/ --to new-landing=/start --goal signup --yes`.

From the dashboard: New experiment → Redirect. It asks for the page to test and the variant pages, and offers "create with a link" for the short-link variant. Experiments created there are cloud-only until `npx splithub pull` writes them into the file.

## Goals on the destination pages

The goal has to fire on the page the visitor lands on. A `pageview` goal with `path: '/thanks'` works everywhere. With the script, `click` goals bind on any page; `event` goals need `splithub.track('…')` on the destination. The visitor id is in the first-party cookie, so attribution crosses pages on the same site. Cookies are not shared across unrelated domains, and the SDK does not import visitor ids from `?sh_vid=`. Cross-domain conversion attribution needs a custom identity integration; short-link click stats work independently.

## Pitfalls

- Caching: a CDN that caches the HTML of `/` for everyone cannot serve per-visitor redirects. The middleware route and the script both run per visitor; make sure the matched page is not fully static-cached, or use the script.
- Loops: do not match the destination path of a variant with the same experiment (`match: '/start*'` while `to: '/start'`).
- Crawlers: bots and headless browsers always get the control and are never counted; `sh.js` never holds or redirects them.


---

<!-- https://splithub.io/docs/targeting -->

# Targeting flows

Who enters an experiment, and with which split, can depend on country, device, browser, UTM parameters, cookies, time, the app's platform and version, or whether the visitor is new or returning. In SplitHub this is a small node graph, the **flow**, on the experiment.

## In the dashboard

Open an experiment → Targeting. The editor has three node types:

- **Condition**: one or more conditions, combined with `match: 'all'` or `'any'`. Fields include `country`, `region`, `city`, `device`, `browser`, `os`, `language`, `referrer`, `url`, `path`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `query`, `cookie`, `visitor`, `hour`, `weekday`, `platform`, `app_version`. For `query` and `cookie`, set `key` to the parameter or cookie name. Operators: `is`, `is_not`, `in`, `not_in`, `contains`, `not_contains`, `starts_with`, `matches`, `exists`, `not_exists`, plus `gte` (at least) and `lt` (below) for `app_version` and `hour`. Values are strings; `in` uses a comma-separated list.
- **Split**: weighted outputs; each output goes to a variant or to another node.
- **Variant** / **Skip**: the leaf. `Skip` means "not in the experiment": the visitor sees the control and no exposure is recorded.

A toggle switches to a **simple list** view (sections top to bottom, drag to reorder) for flows that are just "if country in EU → split A, else → split B". While the flow editor is open, variant editing is locked so the two cannot drift; on save the editor collapses to a one-line summary.

## In the config

The same graph serializes as `flow` on the experiment and comes into `splithub.config.ts` with `npx splithub pull`:

```ts
'hero-title': {
  kind: 'value',
  status: 'running',
  variants: { control: { weight: 1, value: 'A' }, bold: { weight: 1, value: 'B' } },
  flow: {
    start: 'geo',
    nodes: {
      geo:   { type: 'condition', conditions: [{ field: 'country', op: 'in', value: 'DE,AT,CH' }], then: 'eu', else: 'rest' },
      eu:    { type: 'split', outputs: [{ weight: 50, to: 'control' }, { weight: 50, to: 'bold' }] },
      rest:  { type: 'split', outputs: [{ weight: 90, to: 'control' }, { weight: 10, to: 'bold' }] },
      control: { type: 'variant', variant: 'control' },
      bold: { type: 'variant', variant: 'bold' },
    },
  },
}
```

`defineConfig` validates the flow: node references, supported fields and operators, split weights, and declared variant names are checked. Design each path to end in a variant or skip; avoid cycles.

## Apps: platform and version

`platform` is `ios`, `android`, `macos`, `windows`, `linux`, or `web` for a browser. `app_version` is the app's version (`2.4.1`) and is empty on websites. Versions compare part by part, so `2.10.0` is at least `2.9`:

```ts
conditions: [{ field: 'app_version', op: 'gte', value: '2.4' }]   // the dashboard reads it as "App version at least 2.4"
```

Gate an app experiment on the first version that ships its variant code; older builds see the control and are not counted. See [Apps](/docs/apps).

## Where it runs

Everywhere the assignment runs, with the same answer:

- the React SDK (browser context: device, browser, path, query, cookies, time in the visitor's time zone; country, region and city from the cloud's `ctx` when in cloud mode);
- the Next.js middleware (request headers and Cloudflare/Vercel geo);
- the drop-in script `sh.js`, which walks the same flow as the SDK;
- the React Native, iOS and Android SDKs (platform, app version, language, device; country from the cloud);
- server code using `assign(config, experimentId, visitorId, { context })`.

Pass supported context fields with `createClient(config, { context: { country: 'DE' } })` or the provider's `context` prop. For a plan stored in a cookie, use `{ field: 'cookie', key: 'plan', op: 'is', value: 'pro' }`.

## Order of checks

For each visitor and experiment the SDK, the middleware and `sh.js` decide in the same order:

1. a `?sh_force=<id>:<variant>` preview wins and records nothing;
2. crawlers see the control and are never counted;
3. the experiment must be running and inside its schedule;
4. a visitor in the [holdout](/docs/config) sees the control (reason `holdout`);
5. a visitor outside the experiment's [layer](/docs/config) range sees the control (reason `layer`);
6. the `traffic` share, then the flow: a `Skip` leaf gives the control without an exposure (reason `targeting`).

So a flow only ever sees the visitors the holdout and the layer let in. `?sh_debug=1` shows the reason for each decision.

## When to use it

- Roll a change out to one market first.
- Keep a mobile-only variant out of desktop traffic.
- Test only paid traffic (`utm_medium is cpc`).
- Exclude employees by cookie.
- Run an app experiment only on the versions that have its code.

Remember the statistics: targeting narrows the sample. The verdict is about the visitors who entered, not about everyone. When conditions decide which variant a visitor reaches, the expected split depends on who visits, so the split check (SRM) is skipped and the verdict notes say so.


---

<!-- https://splithub.io/docs/goals -->

# Events, goals and revenue

An event is anything your app sends with `track(name, props?)`. A goal is an event marked as one, and it is what an experiment is judged on. Each experiment names one goal; the verdict is computed on it. Other goals can be read beside it as [secondary metrics or guardrails](/docs/config).

## Events

```tsx
const track = useTrack();
track('Video Played', { id: 3 });
```

One call for every event: React `useTrack`, `client.track` in `@splithub/core`, `window.splithub.track` with the drop-in script. Any name is recorded; nothing to declare first. Names use letters, digits, spaces and `_ . : / -`, up to 64 characters. With an analytics property on the provider, every event shows up in its reports; see [Analytics](/docs/analytics).

## Goals

Name any event as an experiment's goal (`--goal "Video Played"` on `create`) and it is a goal: a name that is not in `goals` becomes an event goal keyed by its slug (`video-played`). Declare a goal in the config when you want a label, a value, revenue, a page visit or a click:

```ts
goals: {
  signup:         { type: 'event', name: 'Sign up' },
  purchase:       { type: 'event', revenue: true },
  'video-played': { type: 'event', event: 'Video Played', value: 2 },
  pricing_view:   { type: 'pageview', path: '/pricing' },
  docs_any:       { type: 'pageview', path: '/docs/*' },
  cta_click:      { type: 'click', selector: 'a[href="/start"]' },
}
```

| Type | Fires when |
|---|---|
| `event` | your code calls `track('signup')`, or `track('Video Played')` for a goal with `event: 'Video Played'` |
| `pageview` | a page with that path is viewed; `*` suffix matches a prefix |
| `click` | an element matching the selector is clicked; bound automatically by the SDK and the script |

A click goal is sent as a goal when the element is clicked; raw clicks are not recorded as events. `name` is a label for people, `value` is what one conversion is worth in analytics reports when the event carries no `revenue` prop. Goals count as conversions in every analytics property unless the property's `goals` list narrows them.

Goals can also be made in the dashboard (Settings → Events, the goal switch on an event, or "+ New goal" when creating an experiment) and are delivered to cloud clients. `pull` does not write goal definitions into the file; add them yourself if you want them there. A goal in use cannot be deleted.

## Revenue

```tsx
track('purchase', { revenue: 49 });
```

With `revenue: true` on the goal, results include revenue per variant, and in SplitHub Cloud revenue per visitor (visitors who did not pay count as 0) compared with the control by Welch's t-test. Read it through the API or `results --json`. The verdict stays on the conversion rate; to make sure a variant that converts more does not earn less, add the revenue goal as a guardrail.

## Attribution

A visitor converts for a variant when they sent the goal **at or after their first exposure** to that experiment. In SplitHub Cloud this is decided at ingest; self-hosted stores apply the same rule when they read. Units are unique visitors: ten purchases by one visitor are one conversion (and the summed revenue). At most 50 of one goal per visitor per day are kept. A goal sent before any exposure counts for nothing, which is the right behavior for "did the change cause it". Earlier goals are not retroactively attributed to a later exposure.

In cloud mode ingest accepts events while the project has a running experiment or property and quota left. Goals from visitors who never saw an experiment do not reach any experiment; an analytics property still records the event.

## Props

`track(name, props)` accepts a flat JSON object up to 4 KB (4,096 characters when JSON-serialized); above that, the SDK keeps what fits, `revenue` first. `revenue` is the only key with built-in meaning; the rest is stored with the event and shown in analytics reports, the raw-events view and the CSV export. Keep personal data (emails, names) out of props.

## Pageviews in SPAs

The provider sends a pageview on mount, and the client reports every client-side navigation (history and hash routes) as a pageview after that, so pageview goals fire on route changes without extra code. `usePageview(path)` (React) or `client.pageview(path)` reports a page by hand, for example when navigation tracking is turned off with `trackNavigation: false`.

## Good goals

- One primary goal per experiment, decided before the experiment starts.
- As close to the change as makes sense: a headline experiment on the home page is judged on "clicked the primary button" or "signed up", not on "paid 30 days later". Put the later outcome in `metrics`.
- Counts of unique visitors, not of hits. Repeated clicks by one visitor do not make a variant better.


---

<!-- https://splithub.io/docs/statistics -->

# Statistics and verdicts

SplitHub Cloud turns per-variant counts into a verdict. The same analysis answers the CLI, the MCP server, the dashboard, the reports and the emails, so every surface quotes the same numbers. A self-hosted endpoint returns the raw counts (visitors, conversions, rate, revenue per variant) with `analysis: { available: false }`; verdicts, stars and the rest of this page come with SplitHub Cloud.

## Peeking-safe by design

Agents and people check results all the time. A classic p-value read on every check and acted on at the first significant moment inflates false positives several times over. SplitHub decides with an **always-valid sequential test** (a mixture sequential probability ratio test): its p-value and confidence interval stay valid however often you look, so you can check any time and stop as soon as the verdict says so. Verdicts depend on sample size, not on days.

## What is computed

For each variant: unique exposed visitors, converted visitors, rate, revenue (when the goal has it), and the chance to be the best variant. For each non-control variant against the control:

| Field | Meaning |
|---|---|
| `absoluteLift` | rate − control rate, as a fraction; multiply by 100 for percentage points |
| `relativeLift` | (rate − control rate) / control rate |
| `sequential.pValue`, `sequential.ci` | always-valid p-value and 95% interval of the absolute difference: what decisions use |
| `relativeCi` | the always-valid interval as a relative lift |
| `significant` | the always-valid p-value is below 0.05 after Holm correction across the comparisons |
| `pValue`, `ci`, `zScore` | the fixed-horizon two-proportion z-test, for reference only |
| `probabilityToBeat` | probability that the variant's true rate is above the control's (normal approximation) |

Plus the sample-ratio-mismatch check: a chi-square test of the observed split against the configured weights, flagged when p < 0.001. When a targeting flow's conditions decide who reaches which variant, the expected split depends on who visits, so the check is skipped and `verdict.notes` says so.

## The verdict

| `status` | When | What to do |
|---|---|---|
| `no_data` | no exposures yet | wait, or check the setup with `splithub doctor` |
| `insufficient_sample` | fewer than 100 visitors in a variant or fewer than 50 conversions in total, or the sequential test has not decided yet | keep running; the message says about how many visitors per variant will settle it |
| `srm_detected` | the split does not match the weights | the setup is broken (bots, caching, a variant that errors, a redirect loop); fix it, restart as a new experiment |
| `winner_found` | a variant beats the control, or the control beats a significantly worse variant | read `winner` and `message`, then finish the experiment |
| `no_significant_difference` | every interval rules out a change of 10% or more, or every variant reached the planned sample | ship the simpler variant, finish |
| `guardrail_breached` | a variant is significantly worse on a guardrail goal | do not ship it; find out what broke |

"No difference" must be earned like a winner: the always-valid interval of every comparison sits within ±10% of the control rate (`mde`, the relative effect worth detecting), or every variant passed the sample where the test has 80% power for that effect.

`message` is one sentence written for a person or an agent to act on, for example: *Stop: "bold" beats "control" (+18.3%, always-valid p=0.0120). Ship "bold".* Agents are told in the skills to quote it verbatim and never to call a winner from raw rates. Next to it, `voice` is a friendlier line for people, and `daysToVerdict` estimates when to look again at the current traffic.

When an experiment has run 14 days (or reached its planned sample) with nothing significant and a verdict is more than 30 days off or every lift is under 3%, or when the gap left is so small that proving it would take months, `voice.advice` is `move_on`: the experiment has run its course. It never changes `verdict.status`.

`minDays` (opt-in, 0–30, default 0) holds a verdict until that many days of data are in; waiting messages mention days only when it is set.

## Sample quality and stars

Both are informational: they never change the verdict.

- `verdict.sample.quality` is `small` below the minimums, `good` once every variant has its share of `goodSample` (default 5,000 visitors in total, set per experiment with `goodSample` or `create --good-sample`), and `ok` in between.
- `verdict.sample.stars` (0–5) counts five checks in `verdict.sample.checks`: the minimums are met; the split matches the weights with 1,000+ visitors; the good sample is reached; the sample is big enough to spot a 10% change; it has run a full week. With a broken split the score is capped at 1.

## Sample size

Rule of thumb for a classic test at 95% confidence and 80% power: visitors per variant ≈ `16 · p(1−p) / (p·L)²` with baseline rate `p` and relative lift `L`. Baseline 5% and lift 20% → about 7,600 per variant; baseline 2% and lift 10% → about 78,000. Being safe to check any time costs sample: SplitHub's sequential test needs about twice that (about 16,000 and 170,000 per variant for the same two cases). Ask before you start:

```bash
npx splithub plan --baseline 0.05 --mde 0.2 [--variants 3] [<id>]
```

It answers visitors per variant for SplitHub's test, and with an experiment id the days at that experiment's traffic. No account needed; the same answer is `GET https://go.splithub.io/v1/plan?baseline=0.05&mde=0.2&variants=2`.

## Several variants

With three or more variants every comparison is against the control, and significance is Holm-corrected across the comparisons (same guarantee as Bonferroni, more power). Pairwise comparisons between non-control variants are not reported; create a new experiment with the two finalists if you need that.

## Secondary metrics and guardrails

Goals in `metrics` are read with the same sequential test as the primary goal:

- **secondary**: two-sided, Holm-corrected across all secondary comparisons. Informational.
- **guardrails**: one-sided (harm only, in the direction you set with `worse`), Holm-corrected across all guardrail comparisons, judged once both sides have the minimum 100 visitors. A variant significantly worse on a guardrail is never the winner: the verdict becomes `guardrail_breached` and `verdict.guardrailBreached[]` lists the metric, the variant and the lift. When the decided winner is the control or is clean, the call stands and the harm is added to `verdict.notes`.

Each family is corrected on its own, so adding metrics never weakens the primary verdict.

## Multivariate experiments

An `mvt` experiment gets the verdict over its combinations, plus `factors[]`: for each factor, every level's visitors and conversions summed over the combinations that use it and compared with the factor's first level. Factor levels and combinations are Holm-corrected together, so reading both keeps the 5% false-positive rate. `best` names the level that beats the first one significantly with the largest lift.

## Segments

Breakdowns by country, device, browser, platform, app version, source, channel, landing page and more are for hypotheses, not verdicts: slicing after the fact finds noise. Each segment carries its own comparison and a `small` flag when it has too few visitors. A slice (`results --from --to --filter`) is marked as one and carries no advice; the decision stays with the whole experiment. If a segment looks interesting, run a targeted experiment on it.

## Holdout

With a `holdout` in the config, `splithub results __holdout` compares the held-out visitors with everyone who was enrolled, by the same test: the long-term effect of all your experiments together.


---

<!-- https://splithub.io/docs/react -->

# React

`@splithub/react` collects analytics and renders experiments in any React 18+ app (Vite, CRA, Remix, Astro islands). Next.js App Router has its own package, see [Next.js](/docs/nextjs); so do React Native and Expo, see [React Native and Expo](/docs/react-native).

```bash
npm i @splithub/react @splithub/core
```

## Provider

```tsx
import { SplitHubProvider } from '@splithub/react';
import config from '../splithub.config';

createRoot(document.getElementById('root')!).render(
  <SplitHubProvider config={config} property="sh-x1h78w">
    <App />
  </SplitHubProvider>
);
```

The provider creates the client synchronously, reads or sets the `sh_vid` cookie, applies cached live overrides (cloud mode) and starts the event queue. With `property` it also records pageviews and events for that [analytics property](#analytics). Props: `config`, `property?`, `visitorId?` (SSR: pass the id from the cookie so server and client agree), `overrides?`, `client?`, `pageviews?`, `trackNavigation?`, `context?`, `remote?`, `autoGoals?`, `devtools?`.

## Component experiments

```tsx
import { Experiment, Variant } from '@splithub/react';

<Experiment id="hero-cta">
  <Variant name="control"><Hero /></Variant>
  <Variant name="bold"><HeroBold /></Variant>
</Experiment>
```

One `<Variant>` renders by assignment; the exposure is recorded on mount. Unknown or not-running experiments render the control.

## Value experiments

```tsx
const title = useValue<string>('hero-title');
const price = useValue<number>('price-anchor');
const layout = useValue<{ columns: number; dense: boolean }>('grid');
```

`useValue` returns the control's value when the experiment is not running, so the page never breaks when a test is paused.

## Hooks

| Hook | Returns |
|---|---|
| `useVariant(id)` | the variant key (`'control'`, `'bold'`…); records an exposure the first time |
| `useValue(id)` | the payload of a `value` experiment |
| `useTrack()` | `(name, props?) => void`: an event, any name |
| `useIdentify()` | `(userId, traits?) => void`: ties the visitor to your user; `null` on sign-out |
| `usePageview(path)` | reports a page yourself, for when automatic navigation tracking is off |
| `useSplitHub()` | the underlying `@splithub/core` client |

`useVariant` is for the same experiment in several places: the visitor gets one variant everywhere.

## Goals

```tsx
const track = useTrack();
return (
  <>
    <button onClick={() => track('signup')}>Sign up</button>
    <button onClick={() => track('purchase', { revenue: 49 })}>Buy</button>
  </>
);
```

Pageview goals fire for the current path on load and on every client-side navigation; there is nothing to add to your router. Click goals are bound automatically from the config's selectors.

## Analytics

Name an [analytics property](/docs/analytics) on the provider and the same install collects pageviews and events. `npx splithub analytics connect` adds the prop for you.

```tsx
<SplitHubProvider config={config} property="sh-x1h78w">
  <App />
</SplitHubProvider>
```

- **Pageviews** are automatic: one on load and one on every client-side navigation (`pushState`, `replaceState`, back and forward, hash routes), with time on page and scroll depth. To report pages yourself, pass `trackNavigation={false}` and call `usePageview(pathname)` in the layout.
- **Events**: `useTrack()` is the one call. `track('Video Played', { id: 3 })` records the event in the property and converts every experiment whose goal it is, in one row. Names are letters, digits, spaces and `_ . : / -`, up to 64 characters; props are a flat object up to 4 KB.
- **Users**: call `identify` after sign-in and with `null` on sign-out.

```tsx
import { useEffect } from 'react';
import { useIdentify } from '@splithub/react';

export function IdentifyUser({ user }: { user: { id: string; plan: string } | null }) {
  const identify = useIdentify();
  useEffect(() => {
    if (user) identify(user.id, { plan: user.plan });
    else identify(null);
  }, [identify, user]);
  return null;
}
```

Use your internal user id; keep emails and names out of traits and props. A development build (`NODE_ENV=development`) sends nothing to SplitHub Cloud: check tracking on a deploy or with `vite preview`.

## QA

Append `?sh_force=hero-cta:bold` to any URL to see a variant, running or draft; no exposure is recorded. Keep the parameter in the URL while previewing; it is not saved across navigation. Several at once: `?sh_force=hero-cta:bold,hero-title:outcome`.

To run drafts while you develop without forcing anything, set `runDraftsInDev: true` in the config (see [Drafts in development](/docs/config#drafts-in-development)). Add `?sh_debug=1`, or run `npx splithub dev`, to log every assignment with its reason and get a panel that switches variants. In Vite apps, `splithub()` from `@splithub/core/vite` prints what each experiment does in your dev terminal (see [Drafts in development](/docs/config#drafts-in-development)).

## SSR

Any framework that renders on the server: read the `sh_vid` cookie, pass it as `visitorId` to the provider on both sides, set the cookie on the response when missing. `@splithub/core` exports `newVisitorId()` and `assign()` for server-side decisions.

## Rules

- Never nest an `<Experiment>` inside a `<Variant>` of the same experiment.
- Hooks follow the rules of hooks: no conditional calls.
- Keep the config import at the top of the app; the provider must be above every component that uses a hook.


---

<!-- https://splithub.io/docs/nextjs -->

# Next.js

`@splithub/next` covers the App Router (Next.js 14+): a middleware for the visitor cookie and redirect experiments, helpers for Server Components, and a client provider that agrees with the server on the first byte and collects analytics. `npx splithub init` creates the middleware and prints a provider snippet; add the layout integration below.

```bash
npm i @splithub/next @splithub/react @splithub/core
```

## Middleware

```ts
// middleware.ts
import { splithubMiddleware } from '@splithub/next';
import splitHubConfig from './splithub.config';

export default splithubMiddleware(splitHubConfig);
export const config = { matcher: ['/((?!_next|api|.*\\..*).*)'] };
```

It sets the `sh_vid` cookie, passes the id to Server Components in a header, rewrites the request for `redirect` experiments (the URL in the address bar does not change, the visitor sees no flash) and records edge exposures. In cloud mode it fetches live overrides at most once per 60 s per isolate; opt out with `splithubMiddleware(splitHubConfig, { remote: false })`.

## Layout

```tsx
// app/layout.tsx (Server Component)
import { SplitHubNextProvider } from '@splithub/next/client';
import { getSplitHub } from '@splithub/next/server';
import config from '../splithub.config';

export default async function RootLayout({ children }) {
  const sh = await getSplitHub(config);
  return (
    <html>
      <body>
        <SplitHubNextProvider config={config} property="sh-x1h78w" visitorId={sh.visitorId ?? undefined} remoteOverrides={sh.overrides}>
          {children}
        </SplitHubNextProvider>
      </body>
    </html>
  );
}
```

## Analytics

`property` on `SplitHubNextProvider` names the [analytics property](/docs/analytics) that receives pageviews and events; `npx splithub analytics connect` adds it to your layout. Leave it out and the provider runs experiments only.

- **Pageviews**: one on the first load and one on every App Router navigation, with time on page and scroll depth. No `usePathname()` hook is needed.
- **Events**: `useTrack()` from `@splithub/next/client` in a Client Component. One `track('Signup')` counts in the property and for every experiment whose goal it is.
- **Users**: `useIdentify()` after sign-in, `identify(null)` on sign-out.

```tsx
'use client';
import { useTrack } from '@splithub/next/client';

export function PlayButton({ id }: { id: number }) {
  const track = useTrack();
  return <button onClick={() => track('Video Played', { id })}>Play</button>;
}
```

`next dev` sends nothing to SplitHub Cloud; check tracking on a deployed preview or with `next build && next start`.

## Client Components

Same API as `@splithub/react`, imported from `@splithub/next/client`: `Experiment`, `Variant`, `useVariant`, `useValue`, `useTrack`, `useIdentify`, `usePageview`, plus `Exposure`.

## Server Components

```tsx
import { getSplitHub } from '@splithub/next/server';
import { Exposure } from '@splithub/next/client';
import config from '../../splithub.config';

export default async function Page() {
  const sh = await getSplitHub(config);
  const title = sh.value<string>('hero-title');
  return (
    <>
      <h1>{title}</h1>
      <Exposure id="hero-title" />
    </>
  );
}
```

`getSplitHub(config)` gives `.variant(id)` and `.value(id)` computed from the cookie the middleware set. `<Exposure>` records the exposure once on the client, so a server-rendered variant counts exactly like a client-rendered one.

## Self-hosted ingest route

Install `@splithub/node` and `@splithub/adapter-sqlite` for this example. SQLite requires Node.js 22.13 or newer.

```ts
// app/api/splithub/[[...path]]/route.ts
import { createSplitHubHandler } from '@splithub/node';
import { sqliteStore } from '@splithub/adapter-sqlite';
import config from '../../../../splithub.config';

const handler = createSplitHubHandler({ config, store: sqliteStore(), adminToken: process.env.SPLITHUB_ADMIN_TOKEN });
export const POST = handler;
export const GET = handler;
export const runtime = 'nodejs';
```

In cloud mode this file is not needed.

## Redirect experiments

Declare `kind: 'redirect'` with `match` and a `to` per variant; no code. The middleware rewrites `/` to `/start` for the `new-landing` variant and records the exposure at the edge. Details and the drop-in alternative: [Redirect experiments](/docs/redirect-experiments).

## Why there is no flicker

The middleware decides the visitor id before anything renders. Server Components compute the same deterministic assignment as the client, and the client provider receives that id and the same overrides as props. Both sides agree on the first byte, so hydration never swaps a variant.


---

<!-- https://splithub.io/docs/script -->

# Drop-in script

For sites without a build step (static HTML, Webflow, Framer, Shopify themes, WordPress, landing-page builders) SplitHub Cloud serves a small script that collects analytics, runs redirect experiments and tracks goals from the hosted config.

```html
<script src="https://go.splithub.io/sh.js" data-key="pk_live_…" data-property="sh-x1h78w"></script>
```

Put it in `<head>`, as early as possible. The public key is safe to publish: it can only send events and read the public config.

## What it does on every page

1. Reads the hosted config and live overrides (cached in `localStorage`, refreshed on load when older than 60 s).
2. For `redirect` experiments whose `match` fits the current path: assigns the visitor with the same hash as the SDK (targeting flows included) and, when the variant points elsewhere, navigates to that destination. The rendering hold below reduces flashes.
3. Records the exposure, fires `pageview` goals, binds `click` goals from their selectors, and exposes `window.splithub.track()` and `window.splithub.identify()`.
4. With `data-property`: records a pageview for the [analytics property](/docs/analytics), and another on every client-side navigation.

```html
<button onclick="splithub.track('signup')">Start</button>
<script>
  (window.splithubq = window.splithubq || []).push(['track', 'purchase', { revenue: 49 }]);
</script>
```

## Analytics

`data-property` names the property that receives pageviews and events; without it the script sends no analytics. Find the id on the property's page in the dashboard, or with `npx splithub analytics`.

- **Pageviews**: one per page load and one per client-side navigation (history and hash routes), with time on page and scroll depth. Single-page sites need nothing extra.
- **Events**: `splithub.track(name, props)`, any name of letters, digits, spaces and `_ . : / -` up to 64 characters, props a flat object up to 4 KB. The same call converts every experiment whose goal it is.
- **Users**: `splithub.identify(userId, traits)` after sign-in, `splithub.identify(null)` on sign-out. Use your internal id, never an email.

```html
<script>
  window.splithubq = window.splithubq || [];
  splithubq.push(['track', 'Video Played', { id: 3 }]);
  splithubq.push(['identify', 'user_42', { plan: 'pro' }]);
</script>
```

`window.splithub` exists as soon as the script tag runs, so inline handlers can call it before the config arrives; calls made before the script loads go through the `splithubq` queue. Keep one install per property: if the SDK also runs on the page for the same property, the first to send a page collects pageviews and the other sends only its own `track()` calls.

## Hold rendering during the decision

On a page that is the subject of a redirect experiment, name it so the script holds rendering until the decision is made, even on the first visit with an empty cache:

```html
<meta name="splithub-experiment" content="landing">
```

The script also holds rendering when there is no cached config or a cached redirect matches the page. The meta tag explicitly requests a decision for this page. The hold lasts up to 1,500 ms by default; a timeout can reveal the original page. Put the meta tag before the script.

## What it cannot do

`component` and `value` experiments need the SDK in the app: the script does not change your markup. Use the script for analytics, whole-page tests and goal tracking, the SDK for everything inside the page.

## Options

| Attribute | Default | Meaning |
|---|---|---|
| `data-key` | required | the project's public key |
| `data-property` | none | the analytics property id (`sh-…`); without it no pageviews or events are sent |
| `data-endpoint` | script origin + `/v1/events` | full events URL for a self-hosted cloud or staging |
| `data-hold` | `1500` | maximum rendering hold in ms; `off` disables the hold |

Use `?sh_debug=1` in the page URL for console diagnostics.

## Where experiments come from

Create redirect experiments in the dashboard (New experiment → Redirect) or in `splithub.config.ts` and `push`. Targeting flows (country, device, UTM…) created in the dashboard are evaluated by the script with the visitor's geo from the edge.


---

<!-- https://splithub.io/docs/apps -->

# Apps

SplitHub runs in mobile and desktop apps the same way it runs on a website: one install counts screens and events, and runs experiments with the same verdicts. An app and a website can share a project, so a visitor who signs up on the web and buys in the app is one funnel.

## Pick your SDK

| App | SDK | Install |
|---|---|---|
| React Native, Expo | `@splithub/react-native` | `npx splithub init` (detects Expo and React Native) |
| iOS, macOS (Swift) | Swift package `SplitHub` | Xcode → Add Package Dependencies |
| Android (Kotlin) | `io.splithub:splithub` (+ `splithub-compose`) | one Gradle line |

Guides: [React Native and Expo](/docs/react-native), [iOS (Swift)](/docs/ios), [Android (Kotlin)](/docs/android).

The native iOS and Android SDKs are new (version 0.1). They pass the same assignment tests as the web SDK; expect their API to grow.

## What stays the same

- **Assignment** is the same local hash on every platform: no network call on render, and the same visitor id gets the same variant on web, iOS and Android.
- **Events** are `track(name, props?)`. Any name works; mark one as a goal and experiments count it.
- **Verdicts** come from the same sequential test, with the same split check, minimum sample and stars. See [Statistics](/docs/statistics).
- **The CLI and the MCP server** read app experiments and app analytics with the same commands and tools.

## Screens are page views

A screen is a `page` row: the url is the route (`/product/42` with Expo Router) or `/<screen name>` (`/Settings`), the title is the screen name. So every page report, funnel step (`page:/Checkout`) and pageview goal (`{ type: 'pageview', path: '/Checkout' }`) works on screens with no change.

React Native tracks screens for you with `<ExpoRouterScreens />` or `<NavigationScreens />`. Native apps call `SplitHub.screen("Settings")`, or use `.splithubScreen("Settings")` in SwiftUI and `TrackScreen("Settings")` in Compose.

## Why app experiments live in the cloud

A website deploys in minutes. An app waits for store review, then for people to update, and old versions stay in use for months. So for apps:

- The variants ship inside the build: the code for each version you want to try.
- Everything else lives in the dashboard: start, pause, finish, weights, `value` payloads, targeting. Installed apps pick it up on their next launch, with no release.
- New `value` experiments (copy, prices, flags as JSON) can start from the dashboard, as long as the app reads that experiment.

On the very first launch the SDK waits up to 400 ms for the experiments and shows the control meanwhile. After that it keeps a copy on the device, decides at once, and refreshes in the background. A change never flips a variant in the middle of a session.

That is why native apps always use SplitHub Cloud, and why `init` suggests the cloud for React Native too. A React Native app can still keep `splithub.config.ts`; then `npx splithub push` keeps the cloud and the file in agreement, and pushed experiments reach apps whose build has their variants. Redirect experiments don't apply in an app: use `value` or `component`.

## Target app versions

Every event carries the app's platform and version, so a targeting flow can use them:

| Field | Values | Operators |
|---|---|---|
| `platform` | `ios`, `android`, `macos`, `windows`, `linux`, `web` | `is`, `is_not`, `in`, `not_in` |
| `app_version` | `2.4.1` | `gte` (at least), `lt` (below), and the text operators |

```ts
flow: {
  start: 'new-app',
  nodes: {
    'new-app': { type: 'condition', conditions: [{ field: 'app_version', op: 'gte', value: '2.4' }], then: 'split', else: 'out' },
    split: { type: 'split', outputs: [{ weight: 50, to: 'a' }, { weight: 50, to: 'b' }] },
    a: { type: 'variant', variant: 'control' },
    b: { type: 'variant', variant: 'new-checkout' },
    out: { type: 'skip' },
  },
},
```

Versions compare part by part, so `2.10.0` is at least `2.9`. Gate on the first version that ships the new variant's code: older builds see the control and are not counted. More in [Targeting flows](/docs/targeting).

## Offline and sessions

- Events go out in small batches, and right away when the app moves to the background.
- Without a connection they wait on the device (up to 1,000) and go out later with their original time. Today's numbers can still grow a little when phones come back online.
- A new session starts when the app returns after 30 minutes in the background.
- Development builds send nothing, so your own taps never count. Check tracking with a release build.

## Reports for apps

Make an **app property** for each app: `npx splithub analytics connect` creates one with `kind: 'app'` in an app project, or pick App when you create a property in the dashboard. It uses screens instead of pages and hides the web-only panels.

- **Platform and app version** are dimensions and filters everywhere: `analytics <id> --by app_version`, `results <id> --by platform`, `--filter platform=ios`.
- **Retention** is the report most apps live by: users grouped by the day or week they started, and how many came back after. `npx splithub analytics retention <id>`; see [Reports](/docs/analytics-reports#retention).

## Allowed domains for apps

An app has no web origin, so its app id stands in for one. Add it to an experiment's or property's allowed list next to your sites:

```bash
npx splithub domains set property sh-x1h78w example.com com.acme.shop
```

App ids match exactly. A list that names only websites refuses apps.


---

<!-- https://splithub.io/docs/react-native -->

# React Native and Expo

`@splithub/react-native` runs experiments and collects analytics in React Native and Expo apps. Variants are decided on the device before the first render, screens land in the same reports as your website, and events wait on the device while it is offline. Read [Apps](/docs/apps) first for what differs from the web.

## Install

The quickest way, in the app folder:

```bash
npx splithub init --mode cloud --yes
```

`init` detects Expo or React Native, installs the package and its storage module (through `npx expo install` on Expo), and wraps your entry in `<SplitHubProvider>`: `app/_layout.tsx` with Expo Router, else `App.tsx`. It also adds screen tracking, the agent skills and the MCP entry. When it cannot find the entry, it prints the snippet for you.

By hand, Expo:

```bash
npx expo install @splithub/react-native @react-native-async-storage/async-storage expo-application expo-device
```

Bare React Native (0.72 or newer):

```bash
npm i @splithub/react-native @react-native-async-storage/async-storage
cd ios && pod install
```

Storage keeps the visitor, their variants and unsent events between launches. The package uses `react-native-mmkv` when it is installed, else AsyncStorage. `expo-application` and `expo-device` report the app version and device model; without Expo, pass them yourself (below).

## Provider

```tsx
import { SplitHubProvider, Experiment, Variant, useTrack } from '@splithub/react-native';

export default function App() {
  return (
    <SplitHubProvider publicKey="pk_..." property="sh-x1h78w">
      <Home />
    </SplitHubProvider>
  );
}

function Home() {
  const track = useTrack();
  return (
    <>
      <Experiment id="welcome">
        <Variant name="control"><Text>Welcome to the shop.</Text></Variant>
        <Variant name="short"><Text>Shop in two taps.</Text></Variant>
      </Experiment>
      <Button title="Get started" onPress={() => track('Get Started')} />
    </>
  );
}
```

`publicKey` is your project's public key (`pk_...`), `property` the id of the app's analytics property. Create the `welcome` experiment in the dashboard; until it runs, everyone sees the control.

If you keep experiments in `splithub.config.ts`, pass the config instead (this is what `init` writes):

```tsx
import config from './splithub.config';

<SplitHubProvider config={config} property="sh-x1h78w">
```

Without Expo, pass the app info yourself:

```tsx
<SplitHubProvider publicKey="pk_..." app={{ appId: 'com.acme.shop', version: '2.4.1', build: '412' }}>
```

`app` also takes `device` (`mobile | tablet | desktop`), `storage` (an MMKV instance, AsyncStorage, or any synchronous `getItem` / `setItem` / `removeItem` store) and extra targeting `context`.

## Hooks

The same as in [React](/docs/react), imported from `@splithub/react-native`:

| Hook | Returns |
|---|---|
| `useVariant(id)` | the variant key; records an exposure the first time |
| `useValue(id)` | the payload of a `value` experiment |
| `useTrack()` | `(name, props?) => void`: an event, any name |
| `useIdentify()` | `(userId, traits?) => void`; `null` on sign-out |
| `useScreen(name)` | reports a screen yourself |
| `useAssignment(id)`, `useSplitHub()` | the full decision, the core client |

## Screens

Expo Router, once in `app/_layout.tsx`:

```tsx
import { SplitHubProvider, ExpoRouterScreens } from '@splithub/react-native';

export default function RootLayout() {
  return (
    <SplitHubProvider config={config}>
      <ExpoRouterScreens />   {/* `/`, `/product/42`, ... */}
      <Stack />
    </SplitHubProvider>
  );
}
```

React Navigation:

```tsx
<SplitHubProvider config={config}>
  <NavigationContainer>
    <NavigationScreens />    {/* `/Home`, `/Settings`, ... */}
    <Tabs />
  </NavigationContainer>
</SplitHubProvider>
```

`<NavigationScreens />` finds the container; pass `navigationRef={ref}` if you hold one. The hooks `useExpoRouterTracking()` and `useNavigationTracking(ref)` do the same by hand. Anything else: `useScreen('Checkout')`.

## Launch

AsyncStorage is read into memory once at launch, so variants stay synchronous. The provider renders `fallback` (nothing by default) during that read. To start it earlier, call `prepare()` before the splash screen hides:

```ts
import { prepare } from '@splithub/react-native';
import * as SplashScreen from 'expo-splash-screen';

SplashScreen.preventAutoHideAsync();
prepare().finally(() => SplashScreen.hideAsync());
```

With MMKV there is nothing to wait for. The very first launch also waits up to 400 ms for the dashboard's experiments (control meanwhile); later launches use the saved copy and refresh it in the background.

## Debug builds send nothing

A development build (every Metro debug bundle) sends nothing to SplitHub Cloud, so your own taps never count. Variants still render. To see events arrive, run a release build:

```bash
npx expo start --no-dev --minify
npx expo run:ios --configuration Release
npx expo run:android --variant release
```

Then check with `npx splithub analytics events <property>`, and run `npx splithub doctor` to check the package, the storage module and the provider.

## Example

`examples/expo-app` in the SDK repository: Expo Router, an experiment, screens and an event.


---

<!-- https://splithub.io/docs/ios -->

# iOS (Swift)

The `SplitHub` Swift package runs experiments and collects analytics in iOS and macOS apps. You create experiments in the dashboard; the app picks a variant on the device, with no network call on render, and sends what people saw and did. Read [Apps](/docs/apps) first for what differs from the web.

The iOS SDK is new. iOS 14+ and macOS 11+, no dependencies.

## Install

In Xcode: **File → Add Package Dependencies…**, paste the package URL and add `SplitHub` to your target. Or in `Package.swift`:

```swift
.package(url: "https://github.com/splithub-io/splithub-sdk", from: "0.5.0")
```

`npx splithub init` in an Xcode project prints these lines and a quick start. Native apps have no `splithub.config.ts`: experiments come from SplitHub Cloud.

## Start

Once, as early as you can. The public key (`pk_...`) and the property id (`sh-...`) are in the dashboard.

```swift
import SplitHub

SplitHub.start(publicKey: "pk_...", property: "sh-x1h78w")
```

## Variants and events

```swift
let button = SplitHub.variant("checkout-button")   // "control" or "green"
let price: Int? = SplitHub.value("price")          // payload of a value experiment

SplitHub.track("Purchase", props: ["revenue": 29]) // any event; a goal when marked as one
SplitHub.screen("Settings")                        // a page view of /Settings
SplitHub.identify(userId: "user-42", traits: ["plan": "pro"])
SplitHub.reset()                                   // on logout
```

The first variant of an experiment is the control.

## SwiftUI

```swift
import SwiftUI
import SplitHub

@main
struct ShopApp: App {
    init() {
        SplitHub.start(publicKey: "pk_...", property: "sh-x1h78w")
    }

    var body: some Scene {
        WindowGroup { CheckoutView() }
    }
}

struct CheckoutView: View {
    var body: some View {
        SplitHubExperiment("checkout-button") { variant in
            if variant == "green" {
                Button("Buy now") {}.foregroundColor(.green)
            } else {
                Button("Buy now") {}
            }
        }
        .splithubScreen("Checkout")
    }
}
```

`SplitHubExperiment` records the exposure when the view appears. `.splithubScreen` reports the screen each time it appears.

## Good to know

- **First launch.** The SDK waits up to 400 ms for the experiments (`Options(waitMs:)`) and shows the control meanwhile. Later launches decide at once from the copy on the device.
- **Offline.** Events wait on disk (up to 1,000) and go out when the network is back.
- **Sessions.** A new session starts after 30 minutes in the background.
- **QA.** Force a variant with `Options(force: ["checkout-button": "green"])`. Forced views are never counted.
- **Previews and tests.** SwiftUI previews send nothing. Pass `Options(disabled: true)` in tests.
- **Targeting.** Flows can use `platform` (`ios`, `macos`) and `app_version` (at least / below). See [Targeting flows](/docs/targeting).


---

<!-- https://splithub.io/docs/android -->

# Android (Kotlin)

`io.splithub:splithub` runs experiments and collects analytics in native Android apps. A visitor gets the same variant here as on your website, because assignment is the same hash as the web SDK. Read [Apps](/docs/apps) first for what differs from the web.

The Android SDK is new. Min SDK 21; its only dependency is `androidx.lifecycle:lifecycle-process`, and it brings its own `INTERNET` permission.

## Install

```kotlin
// app/build.gradle.kts
dependencies {
    implementation("io.splithub:splithub:0.5.0")
    // Optional: Jetpack Compose helpers
    implementation("io.splithub:splithub-compose:0.5.0")
}
```

`npx splithub init` in a Gradle project prints these lines and a quick start. Native apps have no `splithub.config.ts`: experiments come from SplitHub Cloud.

## Start

Once, in your `Application`:

```kotlin
class App : Application() {
    override fun onCreate() {
        super.onCreate()
        SplitHub.start(this, "pk_live_...", property = "sh-x1h78w")
    }
}
```

The key is your project's public key. The property is the analytics property for screens and events; leave it out to run experiments only.

## Variants and events

```kotlin
val cta = SplitHub.variant("hero-cta")            // "control", "bold", ...
val price = SplitHub.value("price") as? Map<*, *>  // payload of a value experiment
SplitHub.screen("Settings")                        // a page view of /Settings
SplitHub.track("Video Played", mapOf("id" to 7))   // any event; a goal when marked as one
SplitHub.identify("user-42", mapOf("plan" to "pro"))
SplitHub.reset()                                   // on log out
```

`variant()` and `value()` record an exposure once per variant per session. `valueJson()` gives the payload as JSON text for Gson, Moshi or kotlinx.serialization.

## Compose

```kotlin
@Composable
fun Home() {
    TrackScreen("Home")

    Experiment("hero-cta") { variant ->
        when (variant) {
            "bold" -> Button(onClick = { SplitHub.track("signup") }) { Text("Start free") }
            else -> Button(onClick = { SplitHub.track("signup") }) { Text("Sign up") }
        }
    }

    val price = rememberValue("price")
}
```

`Experiment` records the exposure when the variant is shown and recomposes when variants change.

## Good to know

- **First launch.** The app waits up to 400 ms for the experiments and shows the control meanwhile. Compose helpers update by themselves; in plain views, read variants in `SplitHub.whenReady { }`. Later launches decide at once from the cached copy.
- **Changes** in the dashboard reach the app on its next session, never in the middle of one.
- **Offline.** Events go out every 2 seconds and when the app goes to the background; offline, they wait on the device (up to 1,000).
- **Sessions.** The visitor id stays until `reset()`. A new session starts after 30 minutes in the background.
- **Targeting.** Flows can use `platform` (`android`), `app_version` (at least / below), language, device (`mobile` or `tablet`) and country. See [Targeting flows](/docs/targeting).

## QA

Force a variant on your own device. It's shown but never counted:

```kotlin
SplitHub.start(this, "pk_live_...", options = SplitHubOptions(forcedVariants = mapOf("hero-cta" to "bold"), debug = true))
```

`debug = true` logs every decision under the Logcat tag `SplitHub`.


---

<!-- https://splithub.io/docs/cli -->

# CLI reference

The `splithub` package is the command line for people (prompts, menus) and for agents (flags, `--json`). It covers analytics and experiments, plus notes, short links, alerts and allowed domains. Run it with `npx splithub` or install it as a dev dependency.

```bash
npx splithub                 # interactive menu: experiments, analytics, links, alerts, notes, domains
npx splithub --help          # every command and flag
```

Run commands from the app directory. `--json` prints one line of JSON; errors are `{ error, code, hint? }` with exit code 1.

## Experiments

| Command | Does |
|---|---|
| `init` | Writes `splithub.config.ts`, Next.js middleware and a self-hosted route where applicable, agent skills and MCP entries. Prints the provider snippet for you to add. `--mode cloud` signs in through a link; `--mode self` adds the ingest route and a store. |
| `create` | Adds an experiment to the config. Wizard without flags; flags below. Scaffolds variant components for `component`. The goal can be any event you `track()`. |
| `start <id>` / `pause <id>` / `finish <id>` | Changes `status` in the file and applies it live in cloud mode (within a minute). The experiment must already be pushed and credentials available. |
| `status` | Every experiment with status, visitors, days and the verdict headline; in the cloud also each analytics property's last 7 days. |
| `results <id>` | Full verdict: sample, comparisons, intervals, P(beat), stars, SRM, metrics, factors. Cloud views below. |
| `events --experiment <id>` | The latest raw exposures and goals (`--type exposure\|goal`, `--limit 50`, `--before <ms>`, `--from --to`, `--filter`). 7 days of history, 30 on Pro. |
| `plan` | Visitors an experiment needs, from SplitHub Cloud, no account needed: `--baseline 0.05 --mde 0.1 [--variants 2] [<id>]` (with an id, the days at its traffic). |
| `refs <id>` | Files and lines that use the experiment and its goal. |
| `ship <id> --keep <variant>` | Finishes the experiment, removes it from the config and rewrites the code to the kept variant. `--dry-run` shows the diff. |
| `remove <id>` | Removes an experiment from the config (archived in the cloud when connected). |
| `holdout set <percent>` / `holdout off` | Keeps a share of visitors (up to 50%) out of every experiment to measure the long-term impact; `--goal <event>`. |
| `review [<id>]` | AI reviews stored in the cloud (Pro): at start, on verdict changes, on finish, or on demand. |

### create flags

```bash
--kind value|component|redirect|mvt  --id <key>  --goal <event>  --status running|draft
--name "Hero headline"  --description "..."  --yes
--variants control,b  --weights 50,50                   # value, component, redirect
--value control="Old text" --value b="New text"          # value (repeatable)
--match /path  --to control=/ --to b=/new                # redirect (repeatable)
--factor headline=old:Old,new:New --factor button=blue:#2563eb,green:#16a34a   # mvt (first level = control)
--traffic 50  --max-visitors 10000  --min-days 3  --good-sample 5000  --start <ISO>  --end <ISO>
--secondary pricing_view,signup  --guardrail refunds:higher,errors
--layer checkout:0-50
```

`--traffic` is a percent of visitors. `--guardrail goal:higher` marks a goal where a rise is bad. `--layer key:start-end` enrolls buckets `start` to `end` (end excluded) of a layer; ranges in one layer must not overlap.

### Results views (SplitHub Cloud)

```bash
npx splithub results hero --from 2026-10-01 --to 2026-10-15 --filter country=DE   # a slice
npx splithub results hero --by device         # lift per segment
npx splithub results hero --timeline          # visitors and conversions per day
npx splithub results hero --engagement        # bounce, pages per visit, visit length per variant
npx splithub results hero --events            # every goal and event per variant, lift vs control
npx splithub results hero --by country --export > hero.csv
```

`--from` / `--to` are first-exposure days in the project's time zone. Filters and `--by` dimensions: country, region, city, device, os, browser, language, host, platform, app_version, source, channel, `utm_*`, landing, page. A slice's verdict covers the slice only and carries no advice. `--engagement` and the non-goal rows of `--events` need an analytics property on the same site.

## Analytics

| Command | Does |
|---|---|
| `analytics connect [<id>]` | Picks or creates a property and adds `property="sh-…"` to the app's provider, or prints the `sh.js` tag. `--name "Site"` creates one, `--force` replaces another property named there. |
| `analytics` | Every property with visitors, visits, pageviews and bounce for the last 30 days. |
| `analytics <id>` | One property: totals, users, goals, top pages, top sources, notes. `--by page\|source\|channel\|country\|event\|goal\|…`, `--by variant --experiment <key>`, `--by trait --key <name>`, `--days 7`, `--from --to`, `--filter country=DE`, `--compare [year\|<from>..<to>]`, `--segment <name>`. |
| `analytics create --name "Site"` | Adds a property (id generated, like `sh-x1h78w`); in cloud mode live at once, no push. `--kind site\|app` (default: `app` in an app project) picks a website or an app property. |
| `analytics pause\|resume\|archive\|restore\|remove <id>` | Stops or restarts collecting, archives (cloud), or removes a property. |
| `analytics events <id>` | The latest raw pageviews and events, to check tracking. |
| `analytics funnel <id> --steps "page:/,event:Signup,goal:paid"` | Visitors per step, conversion and drop-off (`--within visit\|7d\|30d`, `--by`). |
| `analytics paths <id> --page /pricing [--prev]` | Where visitors go next, or came from. |
| `analytics retention <id>` | Who comes back, per cohort (`--start visit\|event:<name>\|goal:<key>`, `--return visit\|event:<name>`, `--period day\|week`, `--from --to`). |
| `analytics realtime <id>` | Visitors in the last 5 minutes, top pages and sources. |
| `analytics props <id> --event <name> [--key <prop>]` | An event's prop names, or one prop's values. |
| `analytics export <id>` | CSV to stdout (`--by <dimension>\|day`, `--raw`). |
| `analytics segments` | Saved filters: `--save <name> country=DE …`, `--delete <id\|name>`. |

`properties` is an alias of `analytics`. Self-hosted, `analytics` reads raw counts from your database; reports with filters, `--by`, `--compare`, funnels and retention come with SplitHub Cloud. See [Analytics](/docs/analytics) and [Reports](/docs/analytics-reports).

## Notes, links, alerts, domains (SplitHub Cloud)

| Command | Does |
|---|---|
| `notes` | What happened on a day, marked on experiment timelines and analytics charts (`--experiment <key>` \| `--property <id>`, `--kind note\|issue\|win`, `--days 30`). |
| `notes add "<text>"` | `[--kind issue\|win] [--experiment <key> \| --property <id>] [--day YYYY-MM-DD]`; `notes edit <id> "<text>"`, `notes delete <id>`. |
| `links` | Short links and their clicks; `links <id\|slug>` for one link's clicks. |
| `links create <url> [<url> …]` | `[--slug spring] [--name "Spring sale"] [--weights 70,30]`; `links edit\|pause\|resume\|delete <id\|slug>`. See [Short links](/docs/links). |
| `alerts` | Alert rules and recent alerts; `alerts enable\|disable\|delete\|test <id>`. |
| `alerts add <condition>` | Adds a rule; conditions and flags in [Alerts](/docs/alerts). Rules run on Pro. |
| `domains` | Which domains may send events, per experiment and property; `domains set experiment\|property <id> <domain…>` (an app id like `com.acme.shop` works too), `domains clear experiment\|property <id>`. |

## Project

| Command | Does |
|---|---|
| `push [--dry-run]` | Uploads the normalized config to the cloud. The first push returns the public key and writes it into `storage.key`. Adopts missing dashboard-created experiments into the file. `--dry-run` shows what would change. A key that belonged to another experiment stops the push: `--replace <keys>` (new experiment, old numbers cleared) or `--same <keys>` (same experiment). |
| `pull` | Shows the config stored in the cloud and writes missing dashboard-created experiments, including their flows, into the file. Existing entries are not overwritten. |
| `report` | Status and verdicts as Markdown (raw numbers when self-hosted), with an analytics table in the cloud. |
| `ci init` | Writes `.github/workflows/splithub.yml`: checks on pull requests, a results comment on a schedule. |
| `dev [--url] [--hold]` | Opens the app with `?sh_debug=1` (console and panel: variants, reasons, events) and watches results. |
| `doctor` | Checks config, provider, middleware, route, code references, endpoint reachability, key. |
| `update [--yes]` | Updates `splithub` and the project's `@splithub/*` packages to the latest release. |
| `skills [--mcp]` | (Re)installs the agent skills; `--mcp` also writes `.mcp.json` and `.cursor/mcp.json`. |
| `login [--project <name\|id>]` / `logout` / `whoami` | Connects a folder to a cloud project through a browser approval; shows the project and its public key. |
| `projects` | Lists local directories connected to cloud projects. |

A push uploads the whole file. An experiment the cloud has from an earlier push that the file lacks is removed; `push --dry-run` lists it first. Adding analytics never needs a push.

## init in detail

```bash
npx splithub init --mode cloud --yes                 # link sign-in, then writes everything
npx splithub init --mode cloud --key pk_live_… --yes # public key known; add --no-login to skip browser sign-in
npx splithub init --mode self --db sqlite            # also: postgres | mysql | custom
npx splithub init --no-install --no-login            # files only
npx splithub init --github-action                    # also writes the GitHub workflow
```

`init` looks at the project first:

| Project | What `init` does |
|---|---|
| Next.js, Vite, other React | writes the config and framework files, prints the provider snippet |
| React Native, Expo | installs `@splithub/react-native` and its storage module (`npx expo install` on Expo), wraps `app/_layout.tsx` (Expo Router, adds `<ExpoRouterScreens />`) or `App.tsx` (adds `<NavigationScreens />` with React Navigation); suggests the cloud |
| iOS (Xcode), Android (Gradle) | prints the Swift package or Gradle line and a quick start; always the cloud, no config file |

With `--json`, `app.entry.status` says whether the React Native entry was wrapped (`added`, `already`, or `manual` with a `nextStep`). `doctor` checks the package, the storage module and the provider in a React Native app, and the SDK in the build files of a native one. See [Apps](/docs/apps).

The public key ends up in `storage.key` from the first of: `--key`, the saved credentials of `login`, `SPLITHUB_API_KEY` in the environment (init asks the cloud which project it belongs to), or the first `push`. `init` prints where the key came from. `--no-mcp` skips the MCP entries.

## Where results come from

| `storage.mode` | `status` / `results` read from | Auth |
|---|---|---|
| `self` | your app's handler on the local dev server (`localhost:3000` for Next.js, `5173` for Vite) or `--url` / `SPLITHUB_URL`; raw numbers only | `--token` / `SPLITHUB_ADMIN_TOKEN` when the handler has `adminToken` |
| `cloud` | `https://go.splithub.io/v1` (or `--api` / `SPLITHUB_API`) | the key saved by `login`, `SPLITHUB_API_KEY`, or `--token sk_…` |

## Credentials

`login` prints a code and a URL. You approve it in the dashboard (and can create the project right there); the dashboard mints a project API key for that terminal and the CLI stores it per directory in `~/.config/splithub/credentials.json` (`%APPDATA%\splithub` on Windows). Nobody pastes a secret into a chat. CI and headless agents use `SPLITHUB_API_KEY=sk_…` from the project's Settings → API keys.

`pk_…` is public: it sends events and reads client config. `sk_…` reads results and pushes config: keep it out of git and out of the browser. An API key can be limited to some areas (experiments, analytics, events, notes, links, alerts, domains, each read or write); a command it may not run fails with `INSUFFICIENT_SCOPE` and names the missing `scope`.

## Exit codes and JSON

`0` success, `1` error (with `--json`, the error is printed as `{ error, code, hint? }`). `status --json` returns `{ project, experiments: [{ experiment, kind, status, goal, name, exposures, visitors, conversions, days, verdict, headline, best, sample, stars, voice, daysToVerdict, display }] }`, plus `properties` in the cloud; `results --json` returns the full results object described in [Statistics](/docs/statistics).


---

<!-- https://splithub.io/docs/mcp -->

# MCP server

`@splithub/mcp` is a stdio Model Context Protocol server that exposes the `splithub` CLI as tools. Claude Code, Cursor, Codex, Windsurf or any MCP client can create experiments, read verdicts, start, pause, finish and push, set up analytics and read its reports, and manage notes, alerts, short links and allowed domains, using the same config file and credentials as the CLI. It works the same for websites and for [apps](/docs/apps): React Native, Expo, iOS and Android.

## Register it

`npx splithub init` and `npx splithub skills --mcp` write the entries. By hand:

```json
// .mcp.json (Claude Code, committed) · .cursor/mcp.json (Cursor)
{ "mcpServers": { "splithub": { "command": "npx", "args": ["-y", "@splithub/mcp"] } } }
```

```bash
claude mcp add splithub -- npx -y @splithub/mcp
```

Other clients: command `npx`, args `-y @splithub/mcp`.

Environment: `SPLITHUB_PROJECT_DIR` (defaults to the client's working directory), `SPLITHUB_API` (staging or a self-hosted cloud), `SPLITHUB_API_KEY` (CI), `SPLITHUB_CLI` (path to a specific CLI build).

## Tools

Names follow `splithub_<noun>[_<verb>]`.

### Experiments

| Tool | Does | Notes |
|---|---|---|
| `splithub_status` | every experiment with status, visitors, days, verdict headline | start here |
| `splithub_results` | full verdict for one experiment; `from` / `to` / `filters` for a slice, `by` / `timeline` / `engagement` / `events` for one view (cloud) | the agent reports `verdict.message` verbatim; a slice's verdict is not the experiment's |
| `splithub_experiment_events` | the latest raw exposures and goals of an experiment (cloud) | check the wiring |
| `splithub_plan` | visitors per variant for a baseline and a lift; days at an experiment's traffic | before creating |
| `splithub_experiment_create` | adds an experiment to `splithub.config.ts` | kind `value` / `component` / `redirect` / `mvt`, id, variants (or factors), goal, values, match/to, weights, traffic, maxVisitors, minDays, goodSample, start/end, secondary, guardrails, layer; running by default |
| `splithub_experiment_status` | start / pause / finish | live in cloud mode; after finishing, ask which variant to keep |
| `splithub_refs` | files and lines that use an experiment and its goal | find leftovers |
| `splithub_ship` | finishes, removes from the config, rewrites the code to the kept variant | `dryRun: true` first; returns `diff` and `leftovers` |
| `splithub_remove` | removes an experiment from the config (archived in the cloud) | when the code is already clean |
| `splithub_review` | AI reviews stored in the cloud (Pro) | an analyst's opinion; the verdict stays the source of truth |

### Analytics

| Tool | Does | Notes |
|---|---|---|
| `splithub_analytics_connect` | picks or creates a property and names it on the app's provider | `wired.status` none / many: add the snippet by hand |
| `splithub_analytics` | every property, or one property's totals, goals, top pages and sources; `by` a dimension | counts, never verdicts |
| `splithub_analytics_events` | the latest raw pageviews and events of a property | check tracking after wiring it |
| `splithub_analytics_funnel` / `_paths` / `_realtime` | funnels, next pages, visitors now (cloud) | |
| `splithub_analytics_retention` | cohorts by day or week: `start` (visit, `event:<name>`, `goal:<key>`), `return`, `period` (cloud) | the key report for apps; counts, not an experiment |
| `splithub_segments` | saved report filters (cloud) | |
| `splithub_property_create` | adds a property to `splithub.config.ts` and to the cloud | `kind: site \| app` (default: `app` in an app project); no push needed |
| `splithub_property_status` | pause / resume, archive / restore (cloud), or remove a property | live in cloud mode |

### Around them (SplitHub Cloud)

| Tool | Does |
|---|---|
| `splithub_notes` | what happened on a day, per experiment, property or project: list / add / edit / delete |
| `splithub_alerts` | alert rules: list / add / enable / disable / delete / test (they fire on Pro) |
| `splithub_links` | short links: list / stats / create / edit / pause / resume / delete |
| `splithub_domains` | allowed domains per experiment and property (app ids like `com.acme.shop` too); set or clear one list |

### Project

| Tool | Does | Notes |
|---|---|---|
| `splithub_init` | sets up SplitHub in the project | once per project |
| `splithub_push` / `splithub_pull` | sync the config with the cloud | pull adopts dashboard-created experiments |
| `splithub_doctor` | checks the installation | run after wiring code |
| `splithub_login` | returns a sign-in link and a code | the agent shows it to the user and waits |
| `splithub_whoami` | connected project and public key | |
| `splithub_projects` | every folder on this machine connected to a cloud project | |

`filters` and `by` on `splithub_results` and `splithub_analytics` take `platform` (`ios`, `android`, `web`…) and `app_version` next to country, device, source and the rest. `splithub_init` in a React Native or Expo project installs `@splithub/react-native` and wraps the entry; in an iOS or Android project it returns the install lines and a quick start.

The older names `splithub_create_experiment`, `splithub_set_status`, `splithub_create_property` and `splithub_set_property_status` still answer for one release; use the names above.

Every tool returns the CLI's `--json` output as text. Errors come back with `isError`, the CLI's `code` and what to do next; when the folder is not connected, that is a hint to call `splithub_login`.

## A typical session

1. User: "Add analytics and A/B test the pricing page headline."
2. Agent calls `splithub_analytics_connect`, then `splithub_status` (is anything running on that page?), then `splithub_plan` and `splithub_experiment_create` with `kind: value`, two variants and the `signup` goal.
3. Agent edits the component to read `useValue('pricing-title')`, calls `splithub_doctor` and `splithub_push`, and tells the user it goes live when they deploy.
4. Days later: `splithub_results` → "keep running; about 3,200 visitors per variant will settle it" or "winner found".
5. Agent finishes with `splithub_experiment_status`, asks which variant to keep, and runs `splithub_ship` with `dryRun: true` first.

The [agent skills](/docs/agent-skills) tell the agent these rules; the MCP tools are what it executes them with.


---

<!-- https://splithub.io/docs/agent-skills -->

# Agent skills

`npx splithub init` (and `npx splithub skills`) installs nine skills into the project. A skill is a Markdown file with a front-matter description that a coding agent loads when the task matches. They go to `.claude/skills/<name>/SKILL.md` for Claude Code, to `.cursor/rules/splithub.mdc` for Cursor, and a short section in `AGENTS.md` (or an existing `CLAUDE.md`) points Codex and other agents at them.

| Skill | Loaded when | Teaches |
|---|---|---|
| `splithub` | the user asks to A/B test something, asks which variant wins, or wants notes, alerts, short links or allowed domains | where things live (config, credentials, results), how to create each kind of experiment, how to read a verdict and its slices, what never to do |
| `splithub-analytics` | the user wants traffic numbers, page or source reports, event tracking or funnels, or asks to add analytics | setting up a property with `analytics connect`, sending pageviews, events and `identify`, every report, archiving, allowed domains, billing |
| `splithub-apps` | the project has React Native, Expo, an Xcode project or an Android Gradle build, or the user asks to test or measure an app | install per platform, screens as pages, why app experiments start in the dashboard, `app_version` targeting, platform breakdowns, retention |
| `ab-testing` | before creating an experiment or interpreting results | hypothesis and primary metric, sample size rule of thumb, SRM, peeking, guardrails, when to stop, vocabulary |
| `splithub-api` | writing a server, a script or a non-JS client | the HTTP API: public-key ingest, API keys and scopes, project endpoints for experiments, analytics, notes, links and alerts, errors |
| `splithub-mcp` | connecting SplitHub to Claude Code, Cursor or Codex | how to register the MCP server, the tools, working rules |
| `splithub-self-hosted` | the user wants data in their infra, asks about tables or reports | the events table, the Store interface, Postgres/MySQL/Prisma/Drizzle/Supabase notes, attribution SQL, pulling cloud summaries into a warehouse |
| `splithub-ship` | an experiment has a verdict and the user says ship it, roll out the winner or remove the experiment | finish first, then keep only the winning value, component or page, delete the losers, clean the config, verify, never reuse the id |
| `splithub-loop` | the user asks to run an experiment end to end, or to pick one up where it stands | the whole loop, step by step with the MCP tools and CLI `--json` fields: plan, create, implement, check, push, read results, finish, ship |

## What the main skills say, in short

- `splithub.config.ts` is the source of truth; it ships to the browser, so no secrets.
- Credentials come from `npx splithub login` (a link the human approves). Never ask the user to paste keys.
- One install covers analytics and experiments: `npx splithub analytics connect` names a property on the provider; the same `track()` feeds reports and experiments.
- An experiment's goal can be any event the app tracks; nothing to declare first.
- Prefer `value` experiments (data only) over `component` ones; `redirect` for whole pages; `mvt` only with enough traffic.
- Create the experiment (running by default), wire the code, run `doctor` and `push`. Then always tell the user it goes live when they deploy, and that Pause in the dashboard or `npx splithub pause <id>` holds it.
- To check a draft before it starts: `runDraftsInDev: true` in the config (development only), `?sh_force=<id>:<variant>` on any page, `?sh_debug=1` for the decisions.
- Report `verdict.message` verbatim with the numbers behind it, plus sample quality and stars. `srm_detected` means fix the setup first. A slice or a segment never decides.
- A finished experiment still has its variants in the code: ask which one to keep and whether to remove it, then follow `splithub-ship`.
- Analytics counts are never an experiment result.
- In an app the config ships inside the binary, so new experiments start in the dashboard; gate them on the `app_version` that has their code.
- Never change `seed`, weights or variants of a running experiment; never nest experiments; keep 2–3 experiments per page at most.

## Reading the full text

The skills are plain files in your project after `init`. They are also what the dashboard's "Copy for your agent" prompt refers to, and this documentation covers the same ground page by page. For a single file with everything: [llms-full.txt](/llms-full.txt).

## Updating

`npx splithub skills` rewrites the skill files with the current text from SplitHub Cloud, or with the copies bundled in the installed CLI when the cloud cannot be reached. A file at one of those paths that does not mention SplitHub is left alone unless you pass `--force`. They are safe to commit; agents on the team get the same rules.


---

<!-- https://splithub.io/docs/api -->

# HTTP API

Cloud base URL: `https://go.splithub.io`. Requests and responses use JSON. The [self-hosted handler](/docs/self-hosted) has its own mount path and admin-token authentication. Cloud integrations use two credentials:

- **Public key `pk_…`**: identifies the project to browsers and SDKs. Safe to ship. Can only send events and read the public overrides JSON.
- **API key `sk_…`**: project-scoped secret for servers, CI and the CLI. Minted by `npx splithub login` through a browser approval, or in the dashboard under Settings → API keys. Never in client code.

## Send events (public key)

```http
POST /v1/events
Authorization: Bearer pk_live_…
Content-Type: application/json

{
  "project": "my-app",
  "sdk": "custom/1.0",
  "events": [
    { "id": "e_example_01", "type": "exposure", "exp": "hero-title", "var": "bold", "vid": "v_abc", "sid": "s_1", "ts": 1760000000000, "url": "/" },
    { "id": "g_example_01", "type": "goal", "goal": "signup", "vid": "v_abc", "sid": "s_1", "ts": 1760000010000, "props": { "revenue": 49 } },
    { "id": "p_example_01", "type": "page", "prop": "sh-x1h78w", "url": "/pricing", "title": "Pricing", "ref": "https://www.google.com/", "vid": "v_abc", "sid": "s_1", "ts": 1760000020000 },
    { "id": "v_example_01", "type": "event", "prop": "sh-x1h78w", "name": "Video Played", "props": { "id": 3 }, "url": "/pricing", "vid": "v_abc", "sid": "s_1", "ts": 1760000030000 },
    { "id": "i_example_01", "type": "identify", "prop": "sh-x1h78w", "uid": "user_42", "traits": { "plan": "pro" }, "vid": "v_abc", "sid": "s_1", "ts": 1760000040000 }
  ]
}
```

| `type` | Fields | Meaning |
|---|---|---|
| `exposure` | `exp`, `var`, `url?` | a visitor saw a variant |
| `goal` | `goal`, `props?` | a declared goal, for experiments without an analytics property |
| `page` | `prop`, `url`, `title?`, `ref?` | a pageview of an [analytics property](/docs/analytics) |
| `event` | `prop`, `name`, `props?`, `url?` | a custom event; it also converts the experiments whose goal it is |
| `identify` | `prop`, `uid`, `traits?` | ties the visitor to your user id (1 to 128 characters) |

With a running property, send each action once: a `page` row for a page and an `event` row for a `track()` call. The cloud turns them into the goal conversions of the experiments that measure them; do not send a `goal` row as well.

- `id`: unique per event, 8–64 characters of `[A-Za-z0-9_-]`; stored rows are deduplicated by id. Reuse ids when retrying a failed request; do not replay successful batches.
- `vid`: stable visitor id (the `sh_vid` cookie). `sid`: session id. `ts`: client time in ms; values more than 7 days off are replaced by server time.
- Apps add `"app": { "platform": "ios", "id": "com.acme.shop", "version": "2.4.1", "build": "412", "os": "17.5", "model": "iPhone15,2", "device": "mobile" }` to the batch (`platform` is `ios`, `android`, `macos`, `windows` or `linux`; the rest is optional). It replaces the user agent for device and OS, fills the `platform` and `app_version` dimensions, and `id` stands in for the origin in allowed-domain lists. Screens are `page` rows with the screen's route as `url`.
- Up to 500 events per batch. Goal and event props, and identify traits, may contain up to 4,096 characters of serialized JSON. Event names: letters, digits, spaces and `_ . : / -`, up to 64 characters.
- Reply `202 { ok, received, inserted, dropped }`.
- From a server, send with an API key that has the `events:write` scope instead of the public key: no origin check applies.
- A project with no running experiment or analytics property, or no config yet, replies `202 { ok, inserted: 0, idle: 'no_running' | 'no_config' }`: nothing is stored, and it is not an error.
- `429` with `code` ∈ `quota_exceeded` | `deleted` and a `Retry-After` header: back off; nothing was stored. `403 origin_not_allowed` when nothing in the batch comes from an allowed domain.
- Exposures of experiments that are not running, and rows of properties that are not running, are dropped and not billed. Pageviews and events of a running property count like exposures; goals, identify and engagement are never billed. Rows from bots are dropped.

## Live config for clients (public key)

```http
GET /v1/overrides/pk_live_….json
```

```json
{
  "version": 12,
  "experiments": { "hero-title": { "status": "paused" }, "pricing-cta": { "traffic": 0.5, "weights": { "control": 1, "b": 3 } } },
  "added": [],
  "goals": [ { "key": "signup", "type": "event", "path": null, "revenue": false, "description": null } ],
  "ctx": { "country": "DE", "region": "BE", "city": "Berlin" }
}
```

The browser SDK caches it in `localStorage` for 60 seconds and refreshes stale data when a client is created; with nothing cached (a first visit) it waits for this file up to `remote.waitMs` (default 400 ms) before deciding. `ctx` is the visitor's geo for targeting flows.

`?all=1` also puts every experiment pushed from `splithub.config.ts` that can still assign into `added`, in the pushed shape. Apps ask for it, because the experiments built into an old binary may be out of date; see [Apps](/docs/apps).

## Project endpoints (API key)

```http
GET    /v1/status                       every experiment: status, visitors, days, verdict headline
GET    /v1/results/<experiment>         full verdict (see Statistics)
GET    /v1/reviews[/<experiment>]       AI reviews, newest first (Pro)
GET    /v1/config                       the config stored in the cloud (file + dashboard experiments)
PUT    /v1/config        { config }     push a normalized config (what defineConfig returns)
GET    /v1/overrides                    live overrides
PUT    /v1/overrides/<experiment>  { status | traffic | weights | values }
DELETE /v1/overrides/<experiment>
```

`Authorization: Bearer sk_live_…` on each. Status values: `draft` | `running` | `paused` | `finished`. A `PUT /v1/overrides/<experiment>` that starts or finishes an experiment triggers the start/finish emails to the project's members.

## Analytics endpoints (API key)

```http
GET    /v1/properties                              every property with its last 30 days
POST   /v1/properties     { name, key?, kind?, description?, goals?, status? }   create one (id generated unless given; kind site | app)
GET    /v1/properties/<id>                          one property's settings
PATCH  /v1/properties/<id>  { status | archived | name | kind | description | goals }
DELETE /v1/properties/<id>                          delete a property made in the dashboard, with its numbers
GET    /v1/properties/<id>/summary                  totals, goals, top pages and sources, notes
GET    /v1/properties/<id>/breakdown?by=<dimension> rows by a dimension (goal=, key=, experiment=)
GET    /v1/properties/<id>/funnel?steps=…&within=   funnel steps
GET    /v1/properties/<id>/paths?page=/pricing      next (or previous) pages
GET    /v1/properties/<id>/retention?period=day|week cohorts { start, users, retained[] }
GET    /v1/properties/<id>/realtime                 the last 5 and 30 minutes
GET    /v1/properties/<id>/props?name=<event>       an event's props
GET    /v1/properties/<id>/events                   the latest raw rows (before=, limit= up to 200)
GET    /v1/properties/<id>/export.csv?by=day        CSV (raw=1 for raw rows)
GET    /v1/segments | POST /v1/segments | DELETE /v1/segments/<id>
GET    /v1/event-catalog                            every event name seen and every goal
GET    /v1/domains                                  allowed domains per experiment and property
```

Reports take `from` and `to` (days like `2026-10-01` in the project's time zone, the last 30 days by default, at most 400), filters as query parameters (`country=DE,FR`, `source=(none)`, `t.plan=pro`), and `compare=previous` | `year` | `custom&cfrom=&cto=`. The CLI and the MCP server call these routes; [Reports](/docs/analytics-reports) shows what each one answers.

## API key scopes

A key carries scopes, set when you create it in Settings → API keys. Each area has `<area>:read` and `<area>:write` (write includes read):

| Area | Covers |
|---|---|
| `experiments` | status, results, report, config, overrides, reviews, experiment breakdowns |
| `analytics` | properties and their reports, segments, the event catalog |
| `events` | raw rows (an experiment's or a property's events, raw CSV), and `POST /v1/events` from a server |
| `notes`, `links`, `alerts`, `domains` | those resources |

`read` and `write` alone cover every area, and `*` (the default) covers everything. A request outside a key's scopes answers `403 insufficient_scope` with the missing `scope`. A key for a dashboard of totals needs only `analytics:read`; it cannot read visitors' raw events.

## Health

`GET /v1/health` needs no key. It returns `{ ok, service, version, schema, problems }`; status `503` means the schema check failed.

Use the API-key endpoints above for integrations. Session-based dashboard routes are internal and are not an integration contract.

## Drop-in script

`GET /sh.js` serves the [drop-in script](/docs/script). Public [short links](/docs/links) use `GET https://sh2.uk/<code>` and return `302`. The API-host route `GET /l/<code>` remains supported for compatibility; copy the short URL shown in the dashboard when sharing links.

## Errors

| Code | Meaning |
|---|---|
| 400 | validation; `error` has the message |
| 401 | missing or bad key |
| 403 | forbidden (role, origin) |
| 404 | unknown experiment or project |
| 409 | config has not been pushed (`config_not_pushed`) |
| 429 | gate or rate limit; see `code` and `Retry-After` |

Bodies are `{ error, code, hint? }`; `hint` is the next step, in one sentence.

## Ingest limits

Send at most 500 events per batch. Honor `Retry-After` on `429`. A reply with `idle` means the project records nothing right now; sending more changes nothing until an experiment or a property runs.


---

<!-- https://splithub.io/docs/self-hosted -->

# Self-hosted (your database)

In self mode the app hosts the ingest route and the store; exposures, goals, pageviews and events stay in your database and nothing leaves your infrastructure. The SDK, the CLI and the MCP server are the same as in the cloud; reads are raw counts, while verdicts and analytics reports come with SplitHub Cloud. It is free and has no limits.

```ts
// splithub.config.ts
storage: { mode: 'self', endpoint: '/api/splithub' }
```

## The handler

`@splithub/node` exports one fetch-style handler that works in Next.js route handlers, Remix, Hono, Bun, Deno and plain Node (`toNodeListener` for Express-style servers).

```ts
import { createSplitHubHandler, toNodeListener } from '@splithub/node';
import { sqliteStore } from '@splithub/adapter-sqlite';
import config from './splithub.config';

const handler = createSplitHubHandler({
  config,
  store: sqliteStore({ file: './splithub.db' }),
  adminToken: process.env.SPLITHUB_ADMIN_TOKEN, // protects status and results; health remains public
});

// Next.js app router: export const POST = handler; export const GET = handler;
// Express / Vite / http: app.use('/api/splithub', toNodeListener(handler));
```

Routes relative to the mount path:

| Method | Path | Purpose |
|---|---|---|
| POST | `/` | ingest a batch from the SDK |
| GET | `/status` | every experiment with exposures, visitors and days |
| GET | `/results/:id` | visitors, conversions, rate and revenue per variant |
| GET | `/properties` | every analytics property with raw counts (`?days=30`, or `?from=&to=`) |
| GET | `/properties/:id` | one property's raw counts |
| GET | `/properties/:id/events` | its latest raw pageviews and events (`?before=&limit=`) |
| GET | `/health` | liveness |

The handler accepts up to 500 events per batch and 4,096 characters of serialized props. Set `adminToken` in production; without it, every read above is public.

The CLI reads `status` and `results` from the local dev server (`localhost:3000` for Next.js, `5173` for Vite) or from `--url https://your.app/api/splithub`, with `--token` / `SPLITHUB_ADMIN_TOKEN`.

## Stores

| Store | Package | Notes |
|---|---|---|
| SQLite | `@splithub/adapter-sqlite` | `node:sqlite`, Node 22.13+, zero setup; fine for one server |
| Cloudflare D1 | `@splithub/adapter-d1` | for Workers; `d1Schema()` gives the DDL |
| Postgres | generated | `npx splithub init --mode self --db postgres` writes `splithub/store.ts` using `pg` |
| MySQL | generated | `--db mysql`, uses `mysql2` |
| anything else | `--db custom` | a documented stub with the three methods to fill in (Prisma, Drizzle, Supabase, Mongo…) |

## The Store interface

```ts
interface Store {
  insertEvents(events: StoredEvent[]): Promise<number>;                      // skip existing ids, return inserted count
  variantCounts(experiment: string, goal: string): Promise<VariantCounts[]>;  // per variant: exposures, conversions, revenue
  summaries(): Promise<ExperimentSummary[]>;                                 // per experiment: exposures, visitors, first/last ts
  propertyCounts?(property: string, since: number, until?: number): Promise<PropertyCounts>; // analytics: raw counts
  propertyEvents?(property: string, options: { before: number; limit: number }): Promise<StoredEvent[]>; // newest rows first
  close?(): Promise<void> | void;
}
```

Attribution rule, keep it exactly so self-hosted results equal the cloud's: **a visitor converts for a variant when they sent the goal at or after their first exposure to that variant; exposures and conversions count unique visitors.** `createMemoryStore()` is the reference implementation.

## The events table

One table, one row per event. Column names are yours; the generated stores use these:

| column | type | meaning |
|---|---|---|
| `id` | text, primary key | client-generated, unique; dedupe on it |
| `type` | text | `exposure`, `goal`, `page`, `event`, `engage` or `identify` |
| `experiment`, `variant` | text | for exposures; on analytics rows `experiment` holds the property id |
| `goal` | text | for goals; on `event` rows the event name |
| `visitor_id`, `session_id` | text | the `sh_vid` cookie / the session |
| `ts` | bigint | client time, unix ms |
| `url` | text | page |
| `props` | json | goal or event payload, e.g. `{ "revenue": 49 }`; a page's title and referrer; identify traits |
| `received_at` | bigint | server time, unix ms |
| `host`, `country`, `device`, `browser` | text | optional request metadata for breakdowns |
| `platform`, `app_version` | text | `web` for websites, else the app's platform (`ios`, `android`…) and version |

Indexes: `(type, experiment, visitor_id, ts)` and `(type, goal, visitor_id, ts)`.

## Attribution in SQL

```sql
WITH first_exposure AS (
  SELECT visitor_id, variant, MIN(ts) AS first_ts
  FROM splithub_events WHERE type = 'exposure' AND experiment = $1
  GROUP BY visitor_id, variant
)
SELECT fe.variant,
       COUNT(DISTINCT fe.visitor_id) AS exposures,
       COUNT(DISTINCT g.visitor_id)  AS conversions,
       COALESCE(SUM((g.props->>'revenue')::numeric), 0) AS revenue
FROM first_exposure fe
LEFT JOIN splithub_events g
  ON g.type = 'goal' AND g.goal = $2 AND g.visitor_id = fe.visitor_id AND g.ts >= fe.first_ts
GROUP BY fe.variant;
```

Prisma or Drizzle: map the table in your schema and run this one raw query for `variantCounts`. Supabase: the same SQL as a Postgres function called through `rpc`. Mongo: `$group` by variant and visitor with `$min ts`, then `$lookup` goals.

## Analytics

Self-hosted projects keep their [analytics properties](/docs/analytics) in the config file. `npx splithub analytics create --name "Marketing site"` writes one with a generated id:

```ts
// splithub.config.ts
properties: {
  'sh-x1h78w': { name: 'Marketing site' },
},
```

Name it on the provider (`property="sh-x1h78w"`) and the handler stores its `page`, `event`, `engage` and `identify` rows in the same table. Rows of a property that is not in the config or not running are dropped. Each `event` and `page` row also converts the experiments whose goal is that event or page, so one `track()` call serves both.

Reads are raw counts for a range of UTC days: pageviews, visitors, visits, identified users and events by name.

```http
GET /api/splithub/properties?days=7
GET /api/splithub/properties/sh-x1h78w?from=2026-10-01&to=2026-10-31
```

`npx splithub analytics sh-x1h78w --days 7` prints the same. The SQLite, D1 and generated stores implement `propertyCounts`; a custom store without it answers `501` on a property's counts, and `propertyCountsSql()` from `@splithub/node` gives the queries for the SplitHub table layout. Reports with pages, sources, channels, visits, conversions, filters, funnels, paths and retention come with SplitHub Cloud.

## Reports into your warehouse (cloud mode)

If you use the cloud but want data in your own database: CSV export per experiment and per property (summary, daily timeline, raw events), a webhook channel for alerts and the digest, or a cron that calls `GET /v1/status`, `GET /v1/results/<id>` and `GET /v1/properties/<id>/summary` with the API key and stores the answers. Raw events are a short tail in the cloud (7 days on Free, 30 with packs or Pro) while daily numbers stay much longer: pull summaries, not raw rows, for long-term reporting.

## Do not

- Put database credentials in `splithub.config.ts`; it ships to the browser. They belong in the route's environment.
- Compute winners from raw rates in SQL: raw rates ignore sample size and peeking. Verdicts come with SplitHub Cloud.
- Read analytics counts as an experiment result: use `npx splithub results` for experiments.


---

<!-- https://splithub.io/docs/cloud -->

# SplitHub Cloud

The hosted side: a dashboard at `app.splithub.io`, the ingest and API at `go.splithub.io`. It runs on Cloudflare's edge, so events are accepted close to the visitor, and analytics reports and experiment verdicts are computed from one place.

## Projects and keys

A project is a workspace: one app, its analytics properties, its experiments, its members, its billing. Every project has a **public key** (`pk_…`, in the config and the browser, sends events) and any number of **API keys** (`sk_…`, for the CLI, CI and servers). Members join by invitation email with viewer, editor or admin roles; there is no per-seat price.

## Connecting an app

```bash
npx splithub init --mode cloud     # or: npx splithub login in an existing project
npx splithub push
```

`login` shows a code and a link; approving it in the dashboard (where you can also create the project) mints an API key for that folder. `push` uploads the normalized config; the first push writes the public key into the file. No manual key paste is needed; the CLI stores the secret locally.

## The dashboard

- **Analytics** (where a project opens): every property with visitors, visits, pageviews and bounce; New property, as a website or an [app](/docs/apps).
- **Property page**: Overview, Pages, Sources, Audience, Events & goals, Funnels, Paths, Retention, Realtime, Raw events, Notes, Export and Settings, with a date range, filters, saved segments and a compare period on every report (see [Reports](/docs/analytics-reports)).
- **Experiments**: status, visitors, days, verdict per experiment; start, pause, finish; a quick-start with the one command and a "copy for your agent" prompt.
- **Experiment page**: results, timeline (daily visitors and conversions, cumulative rate), breakdowns by country, device, browser, host, platform and app version, realtime (last 30 minutes), raw events, notes, CSV export, the AI tab, targeting.
- **New experiment**: Redirect, Component or Value, with weights, traffic share, visitor cap, schedule, notes, and the CLI command that creates the same thing in the file.
- **Links**: short links with weighted and targeted destinations and QR codes.
- **Alerts**: rules, channels and the digest (Pro).
- **Setup**: the key, the install command, the drop-in script, the MCP entry.
- **Domains**: which origins (or app ids like `com.acme.shop`) may send events, per experiment and per property.
- **Team**, **Billing**, **Settings** (events and goals, API keys, time zone, project).

## Live overrides

Pause, resume, finish, change `traffic`, reweight, or swap a `value` payload from the dashboard or with `PUT /v1/overrides/<id>`. Overrides sit on top of the config without a deploy. The browser SDK keeps them in a 60-second cache: later pages apply the cached copy at once and refresh it in the background. A visitor's first page has no cache, so the SDK waits for the overrides (about 150 ms, at most `remote.waitMs`, default 400) and renders control meanwhile; then each test is decided once, and the file decides if they are late. Next.js reads them on the server, middleware refreshes its cache on requests, and the script fetches them on page load. A variant never changes once a page has shown it. Experiments the file owns are read-only in the dashboard except for status changes; `pull` brings dashboard-created ones into the file.

## The gate

Before touching the database the edge checks the project. A project with no running experiment or analytics property, or no config, gets `202` with `idle` and the reason; one with no quota left or deleted gets `429` with a reason and `Retry-After`. Exposures for paused, finished or draft experiments, and pageviews and events of paused or archived properties, are dropped. So are analytics rows from bots. Nothing of that is stored or billed. An exposure-event cap (`maxExposures`) finishes the experiment automatically and emails the team.

## Emails

Everyone on the project gets an email when an experiment starts (who, which goal, link) and when it finishes (verdict, per-variant numbers, the AI review on Pro), on every plan. Each member switches these on or off in their profile. Alerts and the digest are additional (Pro).

## Retention

Experiments keep their per-visitor rows and daily numbers for as long as the experiment exists; only the raw event tail expires. Timelines and verdicts of finished experiments keep working after it does.

| | Raw events (custom events, experiment events) | Raw pageviews |
|---|---|---|
| Free | 7 days | 2 days |
| Packs or Pro | 30 days | 2 days |

Analytics reports read visits, not raw rows. Visits stay in full for 90 days: every filter and every per-day visitor count works there. Older days fold into daily sums of the totals and a few dimensions (source, channel, country, page, event and more), so those reports keep working; there, visitors are summed per day, and visit filters, funnels, paths and retention reach back 90 days. Daily sums and goal conversions are kept for 400 days.

## Limits

Up to 500 events per batch, 4,096 characters of serialized props per goal or event, 64-character experiment, variant, goal and event names, and 20 analytics properties per project. Experiments, goals, events, members and projects are unlimited.


---

<!-- https://splithub.io/docs/alerts -->

# Alerts, digest, AI reviews

Three ways to be told instead of checking, for experiments and analytics properties alike. All three live on the Alerts tab and the AI tab of a cloud project and need Pro.

## Alert rules

A rule is a scope, a condition with thresholds, and actions. Experiment rules watch one experiment or every running one; analytics rules watch one property. Rules are evaluated every hour and fire at most once per experiment per cooldown window.

### On experiments

| Condition | Fires when |
|---|---|
| `srm` | the split differs from the configured weights (p < 0.001) |
| `winner` | the verdict is `winner_found` (optionally only once every variant has N visitors) |
| `loser` | a variant is at least X% worse than the control with enough sample |
| `exposures` | unique visitors on the experiment reach N |
| `conversions` | conversions reach N |
| `duration` | the experiment has run N days |
| `no_events` | no exposures for N hours while running |

### On properties

| Condition | Fires when |
|---|---|
| `traffic_drop` | visitors in the last 24 hours fell by X% or more against the same 24 hours a week before (default 50%; needs 20+ visitors a week before) |
| `traffic_spike` | visitors in the last 24 hours rose by X% or more against the same 24 hours a week before (default 50%; needs 20+ visitors now) |
| `goal_silent` | a goal of the property had no conversions in the last N hours (default 24) after converting the week before |
| `event_count` | an event, or any event of the property, reaches N, counted from when the rule was made; with repeat, at every multiple of N |

### On the account

| Condition | Fires when |
|---|---|
| `quota` | the project used X% of its monthly allowance |
| `usage` | this month's billed events cross another multiple of N (every 1,000, say) |

Actions: send to channels, and for experiment rules also pause the experiment, finish it, or drop the losing variant (set its weight to 0). A rule can combine them: "SRM → pause and email", "winner → finish and email", "loser after 10k visitors → drop the loser". Analytics and account rules only notify. `event_count` and `usage` are milestones: each one fires once, whatever the cooldown.

Every project starts with sensible experiment rules created **disabled**; enabling one needs Pro. **Test** runs the rule as a dry run and lists what it would hit right now.

From the CLI:

```bash
npx splithub alerts                                   # rules, progress, recent alerts
npx splithub alerts add srm --pause
npx splithub alerts add loser --lift 10 --experiment checkout-steps --drop-loser
npx splithub alerts add traffic_drop --property sh-x1h78w --percent 50
npx splithub alerts add goal_silent --property sh-x1h78w --goal signup --hours 24
npx splithub alerts add event_count --property sh-x1h78w --event Signup --count 1000 --repeat
npx splithub alerts test <id>                         # what would fire now, nothing sent
```

Other flags: `exposures --visitors N`, `conversions --conversions N`, `duration --days N`, `no_events --hours 24`, `quota --percent 80`, `usage --every 1000`, `winner|loser --min-visitors N`, `--experiment <key>` for one experiment, and on any rule `--name`, `--cooldown <hours>`, `--disabled`, `--finish`. `alerts enable|disable|delete <id>` manage a rule. The MCP tool is `splithub_alerts`.

## Channels

Saved once, reused by rules and the digest: an email address, a Slack or Discord webhook, or a webhook URL of your own (JSON POST with the rule, the experiment or property, the message and the actions taken). Add them on the Alerts tab; pick them in a rule's "deliver to" multiselect. **Test** on a channel sends a test message now.

## The digest

A scheduled summary, separate from the rules: on chosen weekdays, weekly or monthly, at a chosen hour in the project's time zone. It has two parts:

- **Experiments**: running experiments with their verdicts, finished ones since the last digest, quota usage, and what to decide next.
- **Analytics**: per property, visitors, pageviews, top sources and pages, goal conversions and the notable events of the period, each against the period before (up to 10 properties; pick which ones or cover them all).

The team's notes of the period close it. Sent to the chosen channels; each member can also switch it off in their profile.

## AI reviews

An analyst's second opinion written by a language model from the experiment setup, aggregate results and available variant screenshots. Raw event rows and visitor ids are not supplied as statistical input:

- **On start**: a setup review, including available variant screenshots.
- **On finish**: when an experiment finishes (dashboard, CLI, API, cap, rule), a review is written and attached to the finish email.
- **Progress checks**: the daily job checks running experiments with at least 100 visitors. It writes a review when the verdict changes from the previous snapshot or a week has passed since the last review, subject to the automatic review cooldown.
- **On demand**: the AI tab's "Review now".

Reviews are stored with the experiment and readable from the dashboard, `npx splithub review [<id>]`, the MCP tool `splithub_review`, and `GET /v1/reviews[/<id>]` with an API key. They are advice; the verdict from the statistics stays the source of truth, and the skills tell agents exactly that.

## Webhook payload

```json
{
  "kind": "traffic_drop",
  "project": "project-id",
  "subject": "[SplitHub] My app: Traffic drop",
  "text": "Alert summary and dashboard link",
  "rule": "Traffic drop",
  "experiment": null,
  "property": "sh-x1h78w",
  "message": "Visitors to \"sh-x1h78w\" fell 62% in the last 24 hours: 410, against 1,080 the same day last week.",
  "actions": [],
  "link": "https://app.splithub.io/…"
}
```

Experiment alerts carry the experiment key in `experiment` and no `property`; verdict alerts add a `voice` line. Requests carry `X-SplitHub-Event` and `X-SplitHub-Delivery` headers, and `X-SplitHub-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">` when the channel has a signing secret.


---

<!-- https://splithub.io/docs/links -->

# Short links

Short links are links you create and manage in your SplitHub account. Sign in to the [SplitHub dashboard](https://app.splithub.io), select a cloud project, and create a link with one or more destination URLs. From a terminal or an agent: `npx splithub links create https://example.com/spring [--slug spring] [--name "Spring sale"]`, several URLs with `--weights 70,30`; `links` lists them with clicks, `links edit|pause|resume|delete <id|slug>` manages one. The MCP tool is `splithub_links`.

Each link gets a short URL, for example `https://sh2.uk/launch`. Use the short URL shown in the dashboard when sharing a link or creating a QR code.

A link has one or more **destinations**, each with a weight and optional country and device rules. They are useful for campaigns, for QR codes, and for testing landing pages on sites where you cannot install anything.

## Destinations

```json
{ "destinations": [
  { "url": "https://example.com/",       "weight": 50, "label": "current" },
  { "url": "https://example.com/start",  "weight": 50, "label": "new landing" },
  { "url": "https://example.com/de",     "weight": 100, "countries": ["DE", "AT", "CH"] },
  { "url": "https://m.example.com/",     "weight": 100, "devices": ["mobile"] }
] }
```

Matching targeted destinations take priority and are chosen by weight. When none match, the link uses the untargeted destinations. A cookie makes the choice **sticky**, so a visitor who returns lands on the same page. UTM parameters and any other query string on the short link are forwarded unless the destination already defines the same parameter.

## Stats

Total clicks, unique visitors, daily clicks, and breakdowns by destination, country, device and referrer.

## QR codes

Each short link you create in your SplitHub account has a QR code in the dashboard with a PNG download. For colors, a logo and other payload types use the [QR code generator](/tools/qr-generator) with the short URL.

## Links as a lightweight test

Two weighted destinations are a redirect test without the SDK or the script. The dashboard shows the split and the clicks; to judge conversions you need a goal on the destination pages, which is what a [redirect experiment](/docs/redirect-experiments) with the drop-in script gives you. The "Create experiment and its link" option creates the experiment and opens a prefilled link form for you to save. Short-link clicks alone are not experiment exposures; install experiment tracking on the destination site to measure conversions.

## Redirect behavior

The public redirect is `GET https://sh2.uk/<code>` and answers `302`. The API-host route `GET https://go.splithub.io/l/<code>` also remains supported, but the dashboard uses the shorter `sh2.uk` URL. Unknown links return `404`; paused links and links that have reached their click limit return `410`.


---

<!-- https://splithub.io/docs/pricing -->

# Plans and limits

Self-hosted is free with no limits. SplitHub Cloud bills per project and per **exposure**: every pageview and custom event of an analytics property counts like one exposure. Goals, members, experiments and projects are unlimited.

| | Self-hosted | Cloud Free | Packs | Pro |
|---|---|---|---|---|
| Price | $0 | $0 | from $5, prepaid | $19 / project / month |
| Exposures, pageviews and events | unlimited | 50,000 / month | $5 → 250k · $10 → 550k · $25 → 1.5M · $50 → 3.2M | 500,000 / month included |
| Analytics reports (sources, funnels, retention…) | — (raw counts in the CLI) | ✓ | ✓ | ✓ |
| Dashboard, live overrides, targeting, links | — (CLI and MCP only) | ✓ | ✓ | ✓ |
| Alerts, channels, digest | — | — | — | ✓ |
| AI reviews (start, progress checks, finish, on demand) | — | — | — | ✓ |
| Packs | — | — | — | 25% more exposures per pack |
| Raw events kept | your database | 7 days | 30 days | 30 days |
| Analytics visits, then daily sums | your database | 90 days, then 400 days | 90 days, then 400 days | 90 days, then 400 days |
| Experiment numbers and verdicts | your database | while the experiment exists | while the experiment exists | while the experiment exists |
| Members | — | unlimited | unlimited | unlimited |
| Support | GitHub | email | email | priority email |

## What counts

- **An exposure**: one visitor seeing one running experiment, counted once per visitor and experiment; a returning visitor is not counted again. A page with two running experiments costs two exposures per new visitor.
- **A pageview**: one page row of a running analytics property, including each client-side navigation.
- **A custom event**: one `track()` call that reaches a running property.

Each counts as one against the same allowance. Not counted: goals and conversions (including the experiment conversions counted from your events), time on page, scroll depth and identify, exposures of paused, finished or draft experiments and rows of paused or archived properties (refused at the edge), visitors outside `traffic` or skipped by the targeting flow, and bots.

One install sends each action once: a `track('signup')` with a property is one event row that also converts the experiments measuring `signup`, so it is billed once.

## Order of consumption

Free monthly quota → Pro allowance → packs. The free quota and the Pro allowance reset on the first of the month (UTC); packs never expire.

## At the limit

Ingest answers `429 quota_exceeded` with `Retry-After`; the SDK keeps assigning variants locally and your app behaves normally, while no exposures, pageviews or events are stored. The dashboard shows usage. Pro alert rules can notify you at a configured quota threshold. Buying a pack or the month rolling over reopens the gate within a minute.

## Payments

Stripe Checkout for packs and the Pro subscription; invoices and cancellation in the Stripe customer portal from the project's Billing tab. Prices in USD, taxes added where they apply. Check the checkout and billing portal for the applicable payment and cancellation terms.

## Bigger

Several million exposures or pageviews a month, SSO, an SLA, or a reseller arrangement: hello@splithub.io with your expected volume and stack.