Features

A/B Experiments

Split-test anything — copy, layouts, pricing, flows — and measure which variant wins. Flowgrid handles weighted assignment and sticky persistence per visitor through the fg.experiments engine, while exposure and conversion are logged with fg.track(). There are two ways to set this up — a no-code path for marketers (one script tag + the dashboard) and a developer path in code. Both are covered below.

Overview

An experiment has a stable experimentId and two or more weighted variants. When a visitor first hits a page running the experiment, the client engine assigns them a variant by weighted random and stores it in localStorage — so the same visitor always sees the same variant. You render that variant, log an exposure when they see it, and a conversion when they complete your goal.

Already initialised?

These examples assume you've created the SDK client. See the SDK Quickstart — in short, const fg = FlowGrid.init({ webId, apiKey }).

Quick copy: the no-build tag (full guide below)

You don't need a bundler — or any JavaScript. Drop in this single tag and FlowGrid self-initialises from data-site and your data-api-key, then automatically runs every experiment you've set up in the dashboard:

index.html

<script src="https://cdn.flow-grid.xyz/flowgrid.min.js" data-site="YOUR_WEBSITE_ID" data-api-key="YOUR_API_KEY"></script>

On load it fetches your running experiments, assigns the visitor a variant, and applies that variant's redirectUrl (split-URL test) or declarative changes — with an anti-flicker guard and automatic exposure logging. A marketer configures the whole test in the dashboard; no per-variant code is written. (Opt out with data-no-experiments, or call FlowGrid.instance().experiments.initFromServer() yourself — e.g. after client-side navigation in a SPA.)

Want session replay, autoTrack tuning, user identify, or consent control on this no-build path? Set a config object before the tag — every init() option works declaratively:

index.html

<script>
  window.FlowGridConfig = {
    apiKey: "YOUR_API_KEY",   // recommended
    replay: true,             // session replay on
    autoTrack: { heatmaps: true },
  };
</script>
<script src="https://cdn.flow-grid.xyz/flowgrid.min.js" data-site="YOUR_WEBSITE_ID"></script>

Prefer full programmatic control? Add data-manual to the tag to skip auto-init and call FlowGrid.init({ webId, apiKey, replay: true }) yourself. Including your apiKey is recommended for authenticated ingestion.

No-code setup (for marketers & CMS)

If you're on WordPress, Wix, Squarespace, Webflow, Shopify or Framer, you don't need a developer or a build step. Add one script tag once, then create and run every test from the FlowGrid dashboard.

1. Add FlowGrid to your site (once)

Paste this into your site's <head>(most CMSs have a "custom code" or "header scripts" box — see the install guides). It self-initialises from data-site — no JavaScript to write. Add your data-api-key too: experiments still assign variants without it, but your exposures and conversions (the results) are only recorded when the key is present — so the key is required to actually measure a test.

site header

<script src="https://cdn.flow-grid.xyz/flowgrid.min.js" data-site="YOUR_WEBSITE_ID" data-api-key="YOUR_API_KEY"></script>

Already on WordPress with the FlowGrid snippet?

If your site already loads the analytics snippet (core.flow-grid.xyz/flowgrid.js), you don't need a second script — just add data-experiments and your data-api-key to that tag and it loads the experiment engine for you:

site header

<script src="https://core.flow-grid.xyz/flowgrid.js" data-site="YOUR_WEBSITE_ID" data-api-key="YOUR_API_KEY" data-experiments defer></script>

2. Create the experiment in the dashboard

In Analytics → Experiments → New Experiment, give it a name, add your variants, and set the traffic split. That's it — the script on your site picks it up automatically on the next page load and starts assigning visitors.

3. Choose what to test

Split-URL test (no code): give a variant a Redirect URL in the dialog and visitors assigned that variant are sent to that page (e.g. /home-b). FlowGrid handles assignment, stickiness, the redirect, and exposure for you.
Example — test two landing pages: to pit your current homepage against a new design living at /home-v2, create an experiment called "Homepage redesign", add a variant redesign with Redirect URL /home-v2, set a 50/50 split, and click Running. Half your visitors now see the new page; the dashboard shows which one converts better.
On-page tweaks (change a headline, hide a banner, swap a colour): a point-and-click visual editor is coming. Until then, these are added by a developer (see the Developer setup).

4. Track the win

FlowGrid counts who saw each variant automatically. To record a conversion (signup, purchase, …) so the dashboard can pick a winner, add a data-fg-goal attribute. It works on a button, a form, or your thank-you page — no JavaScript:

success action

<!-- count a click as a conversion — no JavaScript -->
<button data-fg-goal="YOUR_EXPERIMENT_ID" data-fg-metric="signup">
  Sign up
</button>

More conversion triggers — still no code

Change the trigger with data-fg-on: load counts a page view (put it on a thank-you page's <body>), submit fires on form submit, view when scrolled into view. data-fg-metric names the goal, data-fg-value records a number, and data-fg-goal="*" counts for every test the visitor is in. A point-and-click visual goal picker is still on the roadmap — but these attributes work today.

5. Watch results & ship the winner

Results stream into the experiment's card in the dashboard. When a variant wins, hit Ship — every visitor is moved onto the winner with no code change and no redeploy.

Want replay, heatmaps or your API key on this path?

Set a config object before the tag — every option works without writing an init() call. Including your apiKey is recommended for authenticated ingestion.

site header

<script>
  window.FlowGridConfig = {
    apiKey: "YOUR_API_KEY",        // recommended
    replay: true,                 // session replay on
    autoTrack: { heatmaps: true },
  };
</script>
<script src="https://cdn.flow-grid.xyz/flowgrid.min.js" data-site="YOUR_WEBSITE_ID"></script>

Notes: add data-no-experiments to skip experiments, or data-manual to turn off auto-init and configure everything in code (see Developer setup). Single-page apps should re-run FlowGrid.instance().experiments.initFromServer() after client-side navigation.

Developer setup — the lifecycle

Step	Method	Where	What it does
1	define()	Admin / server	Register the experiment and its variants once.
2	init()	Browser	Start the client engine — assigns and persists a variant per visitor.
3	variant()	Browser	Read the visitor's assigned variant synchronously and render it.
4	track("experiment_exposure")	Browser / server	Log that the visitor actually saw the variant.
5	track("experiment_conversion")	Browser / server	Log a success metric (signup, purchase, …) against the variant.

1. Define the experiment

Register the experiment once (admin setup or a one-off script). Variant weights are relative — 50 / 50 is an even split.

setup.ts

await fg.experiments.define({
  experimentId: "checkout_v2",
  name: "New checkout flow",
  description: "Single-page vs multi-step checkout",
  variants: [
    { id: "control", weight: 50 },
    { id: "B", weight: 50 },
  ],
});

2. Initialize the client engine

In the browser, call init() with the experiments you want running. This verifies them, assigns the visitor a variant, and persists it.

app.ts

await fg.experiments.init([
  {
    id: "checkout_v2",
    variants: [
      { id: "control", weight: 50 },
      { id: "B", weight: 50 },
    ],
  },
]);

3. Read the variant & render

variant() returns the cached assignment synchronously (or null if none). Branch your UI on it.

checkout.tsx

const variant = fg.experiments.variant("checkout_v2");

if (variant === "B") {
  renderSinglePageCheckout();
} else {
  renderMultiStepCheckout();
}

4. Track exposure

Log an exposure the moment the visitor actually sees the variant — this is what powers your results. The recommended call is fg.track("experiment_exposure", …) with the experiment ID, the user (or anonymous) ID, and the assigned variant.

checkout.tsx

await fg.track("experiment_exposure", {
  experimentId: "checkout_v2",
  userId: "u_1",
  variantId: variant,
});

Tip

Fire exposure on render, not on assignment. A visitor assigned a variant they never saw shouldn't count toward the test.

5. Track conversion

When the visitor completes your goal, log a conversion with a metric name and optional value. The recommended call is fg.track("experiment_conversion", …). In the browser, fg.experiments.localConversion()is a convenience shortcut that reuses the visitor's cached variant so you don't have to repeat it.

conversions.ts

// Recommended — explicit experiment_conversion event
await fg.track("experiment_conversion", {
  experimentId: "checkout_v2",
  userId: "u_1",
  variantId: "B",
  metricName: "purchase",
  value: 49.99,
});

// Browser shortcut — reuses the visitor's cached variant
await fg.experiments.localConversion("checkout_v2", "purchase", 49.99);

Full example

A complete hero-CTA copy test — does "Book a Demo" or "Start Free Trial" drive more sign-ups? This mirrors a real production setup.

hero-cta-experiment.ts

import { FlowGrid } from "flowgrid-sdk";

const fg = FlowGrid.init({ webId: "YOUR_WEBSITE_ID", apiKey: "YOUR_API_KEY" });

const HERO_CTA = "hero_cta_copy";
const VARIANTS = { control: "book_a_demo", treatment: "start_free_trial" } as const;

// 1–2. Define implicitly + initialize the engine
export async function initHeroCta() {
  await fg.experiments.init([
    {
      id: HERO_CTA,
      variants: [
        { id: VARIANTS.control, weight: 50 },
        { id: VARIANTS.treatment, weight: 50 },
      ],
    },
  ]);
}

// 3. Read the assigned variant (falls back to control)
export function getHeroCtaVariant() {
  return fg.experiments.variant(HERO_CTA) ?? VARIANTS.control;
}

// 4. Log exposure when the hero renders
export async function trackHeroExposure(userId: string) {
  await fg.track("experiment_exposure", {
    experimentId: HERO_CTA,
    userId,
    variantId: getHeroCtaVariant(),
  });
}

// 5. Log conversion on signup
export async function trackHeroConversion(userId: string) {
  await fg.track("experiment_conversion", {
    experimentId: HERO_CTA,
    userId,
    variantId: getHeroCtaVariant(),
    metricName: "signup",
  });
}

Server-side rendering

To avoid a flash of the wrong variant, hydrate the visitor's assignment from cookies before reading it on the server. Works with Next.js cookies(), a raw Cookie header (Workers, Hono, Bun), or injected values.

app/page.tsx

import { cookies } from "next/headers";

// Hydrate once per request, then read synchronously
fg.experiments.hydrateFromCookies(cookies());
const variant = fg.experiments.variant("checkout_v2");

// Persist the assignment back to the browser
res.headers.set("Set-Cookie", fg.experiments.serializeAssignmentCookie());

Other runtimes

Outside Next.js use hydrateFromCookieHeader(cookieHeader), or injectAssignments({ checkout_v2: "B" }) when you resolved the variant from your own database.

PreviousTracking parameters Next Form Events

On this page

Overview
No-code setup (CMS)
Developer setup
1. Define
2. Initialize
3. Read & render
4. Track exposure
5. Track conversion
Full example
Server-side rendering

Getting Started

Tracking Campaigns

Features

Installation Guides

Custom Integrations

A/B Experiments

Overview

No-code setup (for marketers & CMS)

1. Add FlowGrid to your site (once)

2. Create the experiment in the dashboard

3. Choose what to test

4. Track the win

5. Watch results & ship the winner

Want replay, heatmaps or your API key on this path?

Developer setup — the lifecycle

1. Define the experiment

2. Initialize the client engine

3. Read the variant & render

4. Track exposure

5. Track conversion

Full example

Server-side rendering