Badgerlytics Docs

An organization is the top-level container for your team and billing. When you sign up you create (or get invited to) exactly one organization. Inside that organization you create one or more properties, which are the websites or apps you actually track.

The split lets you:

• Bill for multiple sites under one plan.
• Share a team across several properties.
• Keep ownership of audiences, custom events, and feature flag definitions inside the property so they don't leak between sites.

Each user in your organization has one of three roles:

• Owner: can manage billing, invite users, and create or delete properties. There's always at least one. Owners can't be removed from the organization, but ownership can be transferred to another member from Organization settings → Users. When you transfer ownership, you become an admin.
• Admin: can do everything the owner can do — invite users, create properties, edit feature flags, change funnels.
• Edit: read access to reports, can run AI Chat Analyst queries, can't change configuration.

Property-level access can be further restricted from Organization settings → Members. Adding a user to your org doesn't automatically grant access to every property — you pick which ones they can see.

A property represents a single site — typically one primary domain, and optionally additional hosts on the same site. It owns its own analytics data, feature flags, funnels, custom events, audiences, and (for SaaS) subscription plans. The tracking script identifies which property an event belongs to via the property ID in window.badgerlyticsConfig.

To create a property:

• From your org dashboard, click + New property.
• Give it a name (e.g. "Store — Production"), the domain, pick an environment label, choose a display currency (USD by default), and confirm the reporting time zone (detected from your browser).
• Copy the install snippet — or grab the SDK package — and drop it on your site.
• Visit your site once with Test mode on to confirm events are landing.

Every property has a primary domain (the main hostname you enter at create time). By default, tracking is accepted on that domain only — plus its automatic www variant. If your product lives across more than one hostname on the same site, add them under Additional hosts when you create or edit the property.

Additional hosts keep everything in one property: one install ID, one set of funnels and flags, and one continuous visitor journey across those hostnames. You can still filter reports by host when you need to compare traffic on each.

This is especially useful for SaaS products that split the experience:

• Marketing site — landing pages, pricing, and content (e.g. www.example.com).
• App site — signup, the product itself, and often billing or account management (e.g. app.example.com).

With both hosts on the same property, you can follow someone from a marketing visit through signup and into billing without stitching together two separate properties.

A few rules to keep in mind:

• Hosts must share the same site root as the primary domain (for example, app.example.com with primary www.example.com). Unrelated domains need their own properties.
• www variants of a listed host are accepted automatically — you do not need to add both.
• You can add up to five additional hosts beyond the primary domain.
• For local development, different ports on localhost count as the same site (for example, localhost:3003 alongside primary localhost:3002).

Each property supports one display currency at a time. This controls how dashboards, reports, and AI summaries format monetary values — for example, which symbol appears next to revenue and MRR. Choose it when you create a property or update it anytime from the property edit dialog.

Supported currencies (USD is the default):

• USD — US Dollar
• CAD — Canadian Dollar
• GBP — British Pound
• EUR — Euro
• AUD — Australian Dollar
• NZD — New Zealand Dollar
• CHF — Swiss Franc

The same list is available when you set currency on SaaS subscription plans in SaaS Setup. We currently support only these codes because our reporting and display layer assumes standard two-decimal minor units (cents, pence, and the like). Currencies such as JPY that do not fit that model are not offered yet.

Display currency is for presentation only. It does not convert amounts stored in your analytics, enforce a single currency in your app code, or change what the tracking script sends on each event. If you track mixed currencies on one property, totals are still summed as raw numbers; pick the currency that best matches how you report revenue.

Badgerlytics subscription billing for your organization remains in USD regardless of this setting.

Each property has one reporting time zone. Dashboards, reports, CSV exports, and AI summaries use it when they group events into calendar days — for example what counts as "today", "last 7 days", or a daily row on a chart. Choose it when you create a property or update it anytime from the property edit dialog.

New properties pick up the time zone from the browser of the person who creates them. If that cannot be detected, they default to UTC. Set the zone your team actually reports in — usually headquarters or the market you care about most — rather than leaving whatever the creator's laptop happened to be set to.

Reports show a short "Times in …" note under the description so you can always see which zone the numbers are using. Changing the setting takes effect immediately: the same events are regrouped into that zone's days. It does not rewrite your stored analytics, and it is not the visitor's own time zone from geolocation.

We strongly recommend using separate properties for production and non-production environments. Don't point your staging or local-dev script at the same property ID as production — you'll pollute your real reports with QA traffic and feature flags that were never meant for users.

A common setup is two properties:

• Production property: your live customers, real traffic only.
• Stage property: integration testing, internal QA, smoke tests, and most local development — point your dev build at the stage ID so QA traffic never hits production reports.

Because you usually want test/stage and production to behave identically, we provide a one-click sync for the things you tend to configure once and keep aligned:

• Feature flags — including iterations and variants
• Custom events — including their dashboard tokens
• Audience traits — labels, types, and tokens for segment rules
• Funnels — step names and orderings

Open the source property, find the resource you want to copy ("Copy to property…"), and pick the destination. For custom events, funnels, and SaaS plans, you can create a new copy or overwrite an existing one with the same identifier. Feature flags and audience traits are create-only: flags get a new token when the destination already has one; traits always copy under the same token and are blocked with an "already exists" message when the destination already has that token. Analytics data itself is never copied — each property owns its own events.

Works for any HTML page, static site generator, or platform that lets you drop a <script> tag into the page.

<!-- In your <head> or just before </body> -->
<script>
  window.badgerlyticsConfig = {
    propertyId: 'your-property-id',
  };
</script>
<script
  src="https://cdn.badgerlytics.com/scripts/badgerlytics.min.js"
  async
></script>

Add the snippet to your theme so it loads on every storefront page — no app install required. A/B tests on Shopify are assigned client-side — the script picks the variation in the browser. See SSR vs. client rendering for what that means for your test design.

<!-- In your <head> or just before </body> -->
<script>
  window.badgerlyticsConfig = {
    propertyId: 'your-property-id',
  };
</script>
<script
  src="https://cdn.badgerlytics.com/scripts/badgerlytics.min.js"
  async
></script>

1. From your Shopify admin, go to Online Store → Themes.
2. On your live theme, open the ••• menu and choose Edit code.
3. Open layout/theme.liquid and paste the snippet just before the closing </head> tag.
4. Click Save, then load your storefront and confirm events with Test mode.

WooCommerce runs on WordPress, so install the snippet site-wide through a header-scripts plugin or your theme's custom-scripts panel. Cart and checkout pages are part of your own site, so the full path to purchase is tracked. A/B tests on WooCommerce are assigned client-side — the script picks the variation in the browser. See SSR vs. client rendering for what that means for your test design.

<!-- In your <head> or just before </body> -->
<script>
  window.badgerlyticsConfig = {
    propertyId: 'your-property-id',
  };
</script>
<script
  src="https://cdn.badgerlytics.com/scripts/badgerlytics.min.js"
  async
></script>

1. Install a header-scripts plugin such as WPCode (Insert Headers and Footers), or use your theme's built-in custom scripts option if it has one.
2. Paste the snippet into the Header area so it renders before </head> on every page.
3. Save, and if you use a caching plugin, purge the page cache so the snippet appears everywhere.
4. Visit your shop, cart, and checkout pages and confirm events with Test mode.

BigCommerce has a built-in Script Manager, so you never need to edit theme files. A/B tests on BigCommerce are assigned client-side — the script picks the variation in the browser. See SSR vs. client rendering for what that means for your test design.

<!-- In your <head> or just before </body> -->
<script>
  window.badgerlyticsConfig = {
    propertyId: 'your-property-id',
  };
</script>
<script
  src="https://cdn.badgerlytics.com/scripts/badgerlytics.min.js"
  async
></script>

1. From your store admin, go to Storefront → Script Manager and click Create a Script.
2. Name it Badgerlytics, set Placement to Head, Location to All pages, category to Analytics, and script type to Script.
3. Paste the snippet into the script contents and save.

Wix supports third-party snippets through the Custom Code panel in your site dashboard. A/B tests on Wix are assigned client-side — the script picks the variation in the browser. See SSR vs. client rendering for what that means for your test design.

<!-- In your <head> or just before </body> -->
<script>
  window.badgerlyticsConfig = {
    propertyId: 'your-property-id',
  };
</script>
<script
  src="https://cdn.badgerlytics.com/scripts/badgerlytics.min.js"
  async
></script>

1. From your site dashboard, go to Settings → Custom Code.
2. Click + Add Custom Code and paste the snippet.
3. Name it Badgerlytics, apply it to All pages with Load code once, and place it in the Head.
4. Click Apply and confirm events with Test mode.

Magento Open Source and Adobe Commerce both let you add the snippet from the admin without touching theme code. A/B tests on Magento (Adobe Commerce) are assigned client-side — the script picks the variation in the browser. See SSR vs. client rendering for what that means for your test design.

<!-- In your <head> or just before </body> -->
<script>
  window.badgerlyticsConfig = {
    propertyId: 'your-property-id',
  };
</script>
<script
  src="https://cdn.badgerlytics.com/scripts/badgerlytics.min.js"
  async
></script>

1. In the admin, go to Content → Design → Configuration and edit your store view.
2. Expand HTML Head and paste the snippet into Scripts and Style Sheets.
3. Click Save Configuration, then flush the cache from System → Cache Management.

@badgerlytics/sdk/react loads the tracking script and exposes hooks like useVariation() and useSetTraits(). Wrap your app in BadgerlyticsProvider with a config object — the provider sets window.badgerlyticsConfig and injects the script for you.

Use this for SPAs (Create React App, Vite, etc.) and as the script install step for Next.js and Remix — pair those frameworks with SSR middleware (SDK) when you need server-side assignment before HTML is sent.

npm install @badgerlytics/sdk

import { BadgerlyticsProvider, useVariation } from '@badgerlytics/sdk/react';

export default function App() {
  return (
    <BadgerlyticsProvider
      config={{ propertyId: 'your-property-id' }}
    >
      <Home />
    </BadgerlyticsProvider>
  );
}

function Home() {
  const heroVariation = useVariation('hero_test', 'control');
  return heroVariation === 'v1' ? <HeroB /> : <HeroA />;
}

<!-- Optional: load via HTML instead of the provider -->
<script>window.badgerlyticsConfig = { propertyId: 'your-property-id' };</script>
<script
  src="https://cdn.badgerlytics.com/scripts/badgerlytics.min.js"
  async
></script>
<!-- Then use <BadgerlyticsProvider autoLoad={false}> so hooks wait for the script -->

Both work — they just hand you different trade-offs:

• SSR (Next.js, Remix, Astro, Nuxt): SDK middleware decides the variation on the server before HTML is sent — no flash of the wrong variant. Setup, API reference, and per-framework examples are in SSR middleware (SDK).
• Client-only (SPAs, static HTML, hosted platforms): the script loads in the browser and assignments apply after first paint. Use the HTML snippet above or BadgerlyticsProvider.

Server and client bucketing agree for the same (visitor, flag, iteration) tuple when both are in use, so you can mix SSR reads and client hooks without skewing results.

Platform support at a glance — SDK frameworks support both rendering modes; hosted platforms run tests client-side:

Add debug: true to window.badgerlyticsConfigwhile you're wiring things up. Badgerlytics logs every event it sends to the console, including payloads and validation warnings — invaluable for double-checking your funnel and product-view shapes before going live.

window.badgerlyticsConfig = {
  propertyId: 'your-property-id',
  debug: true,
  debugLevel: 'info', // 'error' | 'warn' | 'info' | 'debug'
};

Once the script is loaded, window.badgerlytics exposes everything you need. For the full reference (config, automatic events, every method, and payload shapes), see Tracking script API in the sidebar. Quick examples:

// Track when someone views a product (PDP impression)
badgerlytics.trackProductView({
  product_code: 'SKU-123',
  name: 'Running Shoes',
  category: 'footwear',
  price: 9999, // cents
});

// Track a step in a funnel you've set up in the dashboard
badgerlytics.trackFunnelStep('purchase', 3, 'add_to_cart');

// Track a custom event (must be registered in the dashboard first)
badgerlytics.trackCustomEvent('custom_newsletter_signup', {
  source: 'footer',
});

// Set audience traits for personalization / segmentation
badgerlytics.setTraits({
  plan: 'pro',
  signed_in: true,
});

// Read a feature flag variation
const variation = badgerlytics.getVariation('hero_test'); // 'control' | 'v1' | ...
const isOn = badgerlytics.isFlagEnabled('new_pricing_table');

Version 0.4.7 · Last updated September 19, 2026 at 4:36 AM UTC

1. Download badgerlytics-devtools-0.4.7-09-19-2026.zip.
2. Extract the archive to a folder. The folder you select in Chrome must contain manifest.json at its root.
3. Open chrome://extensions in Chrome.
4. Enable Developer mode (toggle in the top-right).
5. Click Load unpacked and choose the extracted folder.
6. Open a page with the Badgerlytics script, then click the extension icon in the toolbar.

The extension does not send analytics, crash reports, or telemetry to Badgerlytics. Event captures and preferences stay in your browser. See the full Chrome extension privacy policy.

All automatic and manual analytics events include these blocks in addition to any event-specific fields below.

You do not call these — the script emits them when tracking is allowed.

// Automatic — no call required
// event_type: "session_start"
// Ingest response (when session_start is accepted):
// { ok: true, geoLocation: { country: "US", city: "Austin", ... } }

// Automatic — no call required
// event_type: "page_view"

// Automatic on tab hide / unload
// event_type: "page_exit"

// Automatic on 2nd pageview in session
// event_type: "non_bounce_session"

// Automatic after flag assignment
// test_data: { flag_key, variation_key, iteration, visitor_id, reason }

// https://yoursite.com/?bai_testForce=hero_test:v1,pricing_test:control

// https://yoursite.com/?bai_bypassCache=true

Location is derived from the visitor's IP at ingest time. It is returned on the session_start ingest response only, then cached for the session. Call getLocation() after onSessionStartReady — it returns null if you read it before that response arrives.

badgerlytics.onSessionStartReady(() => {
  const loc = badgerlytics.getLocation();
  if (!loc) return;
  console.log(loc.city, loc.regionCode);
});

badgerlytics.onSessionStartReady(() => {
  const loc = badgerlytics.getLocation();
  if (loc?.metroCode === '635') {
    // Austin DMA
  }
});

First-party cookies (path /, SameSite=Strict). SSR middleware may also write flags and traits; the script reads them on load.

Session-only sessionStorage: _bai_pvc (pageview count), _bai_funnel_{name} (furthest funnel step per name).

The @badgerlytics/sdk middleware packages assign A/B test and feature-flag variations on the server before HTML is sent, so visitors never see a flash of the wrong variant. Install the package for your framework, add middleware once, then read assignments in pages, loaders, or server components.

npm install @badgerlytics/sdk

Import paths and peer dependencies:

• @badgerlytics/sdk/nextjs — requires next>= 13.4
• @badgerlytics/sdk/remix — React Router 7+ or Remix 2+
• @badgerlytics/sdk/nuxt — Nuxt 3+
• @badgerlytics/sdk/astro — Astro 4+

Middleware handles assignment cookies and SSR reads only. You still need the browser tracking script for page views, commerce events, and client-side hooks.

Astro and Nuxt: use the HTML snippet below (or your framework's equivalent). Remix / React Router can use BadgerlyticsProvider the same way as Next.js.

<!-- Still required for page views, commerce events, and client-side flags -->
<script>
  window.badgerlyticsConfig = { propertyId: 'your-property-id' };
</script>
<script src="https://cdn.badgerlytics.com/scripts/badgerlytics.min.js" async></script>

Tracking script embed — also documented under Script Installation.

These exports are available from every middleware package (/nextjs, /remix, /nuxt, /astro):

• createBadgerlyticsMiddleware(options) — assign variants before SSR; write _bai_visitor and _bai_flags cookies.
• getVariation(source, flagKey, fallback?) — variation key (e.g. control, v1).
• getAssignments(source) — assignment map for the request ({ flagKey: { i, v, reason? } }).
• getVisitorId(source) — stable visitor id for this request.
• getTraits(source) — merged trait bag used for segment rules (cookie traits plus built-ins like visitor_type, device_type, page_path, and UTM params).
• isFlagEnabled(source, flagKey) — true when the visitor is on the v1 arm (control is off).
• isVariation(source, flagKey, expected) — compare to a specific variation key.
• setTraitsOnResponse(response, traits) — set or clear _bai_traits on login/logout (Next.js, Remix, Astro API routes).
• runBadgerlyticsAssignment(request, options) — run assignment outside global middleware.
• readVisitorFromRequest / readTraitsFromRequest / readFlagsFromRequest — read cookies from a Web Request.
• Cookie/header constants: VISITOR_COOKIE, FLAGS_COOKIE, TRAITS_COOKIE, x-bai-assignments, x-bai-visitor, x-bai-traits.

createBadgerlyticsMiddleware accepts:

createBadgerlyticsMiddleware({
  propertyId: 'your-property-id', // required — public hashid from the app
  skipBots: true,                 // default — skip assignment for bot user-agents
  skip: (request) => false,       // optional — return true to skip this request
  cookieDomain: '.example.com',  // optional — Set-Cookie Domain attribute
  cookieSecure: true,            // optional — Set-Cookie Secure flag
  cookieSameSite: 'lax',         // optional — default 'lax'; also 'strict' | 'none'
  cookieMaxAgeSec: 31536000,     // optional — default 365 days
});

source for read helpers depends on the framework — see the Next.js, Remix, Nuxt, and Astro sections below. Next.js and Remix forward x-bai-* headers on the request; Nuxt uses event.context; Astro uses Astro.locals. The skip callback receives a NextRequest or Web Request on Next.js and Remix, an h3 event on Nuxt, and MiddlewareContext on Astro.

Next.js uses two packages: @badgerlytics/sdk/nextjs (this section) for SSR assignment, and @badgerlytics/sdk/react for BadgerlyticsProvider — which loads the tracking script and client hooks without a manual embed. Use the same propertyId in both.

1. Middleware — add root middleware.js:

// middleware.js (project root)
import { createBadgerlyticsMiddleware } from '@badgerlytics/sdk/nextjs';

export const middleware = createBadgerlyticsMiddleware({
  propertyId: 'your-property-id',
});

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

2. Provider — wrap your app in app/layout.jsx (or pages/_app.jsx):

// app/layout.jsx — use with middleware.js (same propertyId)
import { BadgerlyticsProvider } from '@badgerlytics/sdk/react';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <BadgerlyticsProvider config={{ propertyId: 'your-property-id' }}>
          {children}
        </BadgerlyticsProvider>
      </body>
    </html>
  );
}

Read assignments — Pages Router:

import {
  getVariation,
  getAssignments,
  getVisitorId,
  getTraits,
  isFlagEnabled,
} from '@badgerlytics/sdk/nextjs';

export async function getServerSideProps({ req }) {
  return {
    props: {
      hero: getVariation(req, 'hero_test', 'control'),
      allFlags: getAssignments(req),
      visitorId: getVisitorId(req),
      traits: getTraits(req),
      pricingOn: isFlagEnabled(req, 'new_pricing_table'),
    },
  };
}

Read assignments — App Router:

import { headers } from 'next/headers';
import {
  getVariation,
  getAssignments,
  getTraits,
  isFlagEnabled,
} from '@badgerlytics/sdk/nextjs';

export default async function Page() {
  const h = await headers();
  const hero = getVariation(h, 'hero_test', 'control');
  const traits = getTraits(h);
  const pricingOn = isFlagEnabled(h, 'new_pricing_table');
  return hero === 'v1' ? <HeroB traits={traits} /> : <HeroA />;
}

Set audience traits — Route Handlers and legacy pages/api:

import { setTraitsOnResponse } from '@badgerlytics/sdk/nextjs';

// App Router Route Handler
export async function POST(request) {
  const user = await authenticate(request);
  const response = Response.json({ ok: true });
  setTraitsOnResponse(response, { signed_in: true, plan: user.plan });
  return response;
}

// Legacy pages/api — Node res is supported
export default function handler(req, res) {
  setTraitsOnResponse(res, { signed_in: true });
  res.status(200).json({ ok: true });
}

Manual assignment (without global middleware):

import { runBadgerlyticsAssignment } from '@badgerlytics/sdk/nextjs';

export async function GET(request) {
  const result = await runBadgerlyticsAssignment(request, {
    propertyId: 'your-property-id',
  });
  if (!result.ok) return Response.json({ skipped: result.reason });

  const response = Response.json({ assignments: result.assignments });
  for (const cookie of result.setCookieHeaders) {
    response.headers.append('Set-Cookie', cookie);
  }
  return response;
}

Next.js only: writeAssignmentCookies(NextResponse, opts) — used by the built-in middleware to set visitor + flags via NextResponse.cookies.

Enable route middleware in react-router.config.js, then register Badgerlytics in app/middleware.ts or export from app/root.jsx. Loaders and actions receive a request with forwarded x-bai-* headers — pass that to getVariation(request, …).

// react-router.config.js — required for route middleware (React Router 7+)
export default {
  ssr: true,
  future: {
    v8_middleware: true,
  },
};

// app/middleware.ts (or export from app/root.jsx)
import { createBadgerlyticsMiddleware } from '@badgerlytics/sdk/remix';

export const middleware = [
  createBadgerlyticsMiddleware({ propertyId: 'your-property-id' }),
];

Read assignments in a loader:

import {
  getVariation,
  getAssignments,
  getVisitorId,
  getTraits,
  isFlagEnabled,
  isVariation,
} from '@badgerlytics/sdk/remix';

export async function loader({ request }) {
  return {
    hero: getVariation(request, 'hero_test', 'control'),
    allFlags: getAssignments(request),
    visitorId: getVisitorId(request),
    traits: getTraits(request),
    isHeroV1: isVariation(request, 'hero_test', 'v1'),
    pricingOn: isFlagEnabled(request, 'new_pricing_table'),
  };
}

Set audience traits in an action:

import { setTraitsOnResponse } from '@badgerlytics/sdk/remix';
import { redirect } from 'react-router';

export async function action() {
  const user = await login();
  const response = redirect('/app');
  setTraitsOnResponse(response, { signed_in: true, plan: user.plan });
  return response;
}

Manual assignment:

import {
  runBadgerlyticsAssignment,
  writeAssignmentCookiesOnResponse,
} from '@badgerlytics/sdk/remix';

export async function loader({ request }) {
  const result = await runBadgerlyticsAssignment(request, {
    propertyId: 'your-property-id',
  });
  if (!result.ok) return { skipped: result.reason };

  const headers = new Headers(result.forwardHeaders);
  // Merge forwardHeaders onto a sub-request, or return assignments in loader data
  return { assignments: result.assignments };
}

Also available: writeAssignmentCookiesOnResponse(response, opts) to append visitor + flags Set-Cookie headers on a Web Response.

Add server/middleware/badgerlytics.ts. Server routes read from event.context.badgerlytics via the *FromEvent helpers — not getVariation(event).

// server/middleware/badgerlytics.ts
import { createBadgerlyticsMiddleware } from '@badgerlytics/sdk/nuxt';

export default createBadgerlyticsMiddleware({
  propertyId: 'your-property-id',
});

Read assignments:

import {
  getVariationFromEvent,
  getAssignmentsFromEvent,
  getVisitorIdFromEvent,
  getTraitsFromEvent,
  isFlagEnabledFromEvent,
} from '@badgerlytics/sdk/nuxt';

export default defineEventHandler((event) => {
  return {
    hero: getVariationFromEvent(event, 'hero_test', 'control'),
    allFlags: getAssignmentsFromEvent(event),
    visitorId: getVisitorIdFromEvent(event),
    traits: getTraitsFromEvent(event),
    pricingOn: isFlagEnabledFromEvent(event, 'new_pricing_table'),
  };
});

Set audience traits — use setTraitsOnEvent, not setTraitsOnResponse:

import { setTraitsOnEvent } from '@badgerlytics/sdk/nuxt';

export default defineEventHandler(async (event) => {
  const user = await login(event);
  setTraitsOnEvent(event, { signed_in: true, plan: user.plan });
  return { ok: true };
});

Manual assignment:

import { runBadgerlyticsAssignmentForEvent } from '@badgerlytics/sdk/nuxt';

export default defineEventHandler(async (event) => {
  const result = await runBadgerlyticsAssignmentForEvent(event, {
    propertyId: 'your-property-id',
  });
  if (!result.ok) return { skipped: result.reason };
  return { assignments: result.assignments };
});

Nuxt-specific exports:

• getVariationFromEvent, getAssignmentsFromEvent, getVisitorIdFromEvent, getTraitsFromEvent, isFlagEnabledFromEvent
• setTraitsOnEvent(event, traits)
• runBadgerlyticsAssignmentForEvent(event, options)

Wrap createBadgerlyticsMiddleware in defineMiddleware. Read assignments from Astro.locals — Astro does not replace the incoming request, so header-based getVariation will not work in .astro frontmatter.

// src/middleware.js
import { defineMiddleware } from 'astro:middleware';
import { createBadgerlyticsMiddleware } from '@badgerlytics/sdk/astro';

export const onRequest = defineMiddleware(
  createBadgerlyticsMiddleware({ propertyId: 'your-property-id' })
);

Read assignments in a page:

---
import {
  getVariationFromLocals,
  getAssignmentsFromLocals,
  getVisitorIdFromLocals,
  getTraitsFromLocals,
  isFlagEnabledFromLocals,
} from '@badgerlytics/sdk/astro';

const hero = getVariationFromLocals(Astro.locals, 'hero_test', 'control');
const traits = getTraitsFromLocals(Astro.locals);
const pricingOn = isFlagEnabledFromLocals(Astro.locals, 'new_pricing_table');
---
{hero === 'v1' ? <HeroB traits={traits} /> : <HeroA />}

Set audience traits in an API route:

import { setTraitsOnResponse } from '@badgerlytics/sdk/astro';

export const POST = async ({ request }) => {
  const user = await authenticate(request);
  const response = new Response(JSON.stringify({ ok: true }), {
    headers: { 'Content-Type': 'application/json' },
  });
  setTraitsOnResponse(response, { signed_in: true, plan: user.plan });
  return response;
};

Manual assignment:

import { runBadgerlyticsAssignment } from '@badgerlytics/sdk/astro';

export const GET = async ({ request }) => {
  const result = await runBadgerlyticsAssignment(request, {
    propertyId: 'your-property-id',
  });
  if (!result.ok) return new Response(JSON.stringify({ skipped: result.reason }));

  const response = new Response(JSON.stringify({ assignments: result.assignments }));
  for (const cookie of result.setCookieHeaders) {
    response.headers.append('Set-Cookie', cookie);
  }
  return response;
};

Astro-specific exports (all use Astro.locals):

• getVariationFromLocals, getAssignmentsFromLocals, getVisitorIdFromLocals, getTraitsFromLocals, isFlagEnabledFromLocals

• Where to read flags: Next.js and Remix → getVariation(request | req | headers()). Nuxt → getVariationFromEvent(event). Astro → getVariationFromLocals(Astro.locals).
• Setting traits on login: Next.js, Remix, and Astro API routes → setTraitsOnResponse. Nuxt → setTraitsOnEvent.
• Manual assignment without middleware: Web Request → runBadgerlyticsAssignment. Nuxt → runBadgerlyticsAssignmentForEvent.
• Edge vs Node: Middleware runs wherever your framework deploys it. The property CDN embed must be reachable from that runtime.
• Bucketing parity: Server and browser use the same (visitorId, flagKey, iteration) seed, so SSR and client assignments stay aligned when cookies are present.
• QA overrides: Append ?bai_testForce=flag_key:variation to force a variation for that request (same format as the tracking script). Forced assignments are forwarded to SSR but not written to cookies.

A standard purchase funnel works well for most stores:

• 1 — Product listing page (PLP)
• 2 — Product display page (PDP)
• 3 — Add to cart
• 4 — View cart
• 5 — Payment / review
• 6 — Conversion

Set these up once under Funnels and call trackFunnelStep('purchase', n, name) as users reach each step.

Fire one product view per PDP visit. The event is what powers the "most-viewed products" report and the view-to-purchase conversion rate.

// On every product detail page
window.badgerlytics.trackProductView({
  product_code: 'SKU-7421',
  name: 'Trail Runner — Size 10',
  category: 'footwear',
  price: 12999, // cents
});

Fire after any change to the cart. The payload should always reflect the full cart, not just the delta — we use it as a snapshot for the abandoned-cart reports.

// After any cart change: add, remove, qty update
window.badgerlytics.trackCartUpdate({
  subtotal: 25998, // cents — full cart subtotal
  currency: 'USD',
  cart_id: cartId,
  products: cart.items.map((item) => ({
    product_code: item.sku,
    name: item.name,
    category: item.category,
    price: item.priceCents,
    quantity: item.quantity,
  })),
});

Fire on the order-confirmation page. Include the full line-item breakdown — we use it for revenue-by-category, revenue-by-SKU, and to attribute the purchase back to the product views that led to it. Calls made while the tracking script is still initializing are buffered and sent automatically once it's ready, so an inline call on the confirmation page is safe.

// On the order-confirmation page
badgerlytics.trackConversion({
  order_id: order.id,          // your order id
  order_total: order.totalCents,
  total_tax: order.taxCents,        // optional
  total_discount: order.discountCents, // optional
  total_shipping: order.shippingCents, // optional
  currency: 'USD',
  customer_id: order.customerId,    // optional, enables cohort retention
  discounts: order.discounts?.map((d) => ({
    code: d.code,
    discount_name: d.name,
    discount_amount: d.amountCents,
  })),
  products: order.lineItems.map((item) => ({
    product_code: item.sku,
    sku: item.sku,
    name: item.name,
    category: item.category,
    price: item.priceCents,
    quantity: item.quantity,
    // billing_interval defaults to 'one_time' for ecommerce
  })),
});

• A cart streak is "abandoned" when the visitor sends a cart_update and no conversion arrives within a locked 1-day window after the last cart update. The report only includes streaks whose window has fully closed (see complete_through in the app). Same-day carts are still maturing until tomorrow.
• Conversions that happen later — even after the maturity window — still mark the streak as converted when we see them in your data (we look ahead up to 30 days when classifying streaks). A customer who returns two days later and buys counts as converted, not abandoned.

A typical SaaS funnel: landing → pricing → signup → activation → conversion. Set this up under Funnels and fire each step with badgerlytics.trackFunnelStep(name, n, step) as the user reaches it.

Fire one product view per plan a visitor sees on your pricing page. This powers the "most-viewed plan" numbers and the plan-level conversion rates.

// Fire when a visitor lands on a plan / pricing page
badgerlytics.trackProductView({
  product_code: 'pro_monthly', // your plan_code
  name: 'Pro (Monthly)',
  category: 'pro',             // your tier_label
  price: 15900,                // cents
});

Once the user has selected a specific plan and started checking out, send a cart update so we can attribute their conversion (or abandonment) back to the plan they chose.

// Fire after the visitor picks a plan (e.g. on the checkout / review step)
badgerlytics.trackCartUpdate({
  subtotal: 15900,
  currency: 'USD',
  cart_id: 'session-abc123',
  products: [
    {
      product_code: 'pro_monthly',
      name: 'Pro (Monthly)',
      category: 'pro',
      price: 15900,
      quantity: 1,
      billing_interval: 'month',
      interval_count: 1,
    },
  ],
});

Fire a conversion event when a subscription starts. Conversion count and funnels use this event. Recurring MRR does not: it comes from the product line's price plus billing_interval, or from a later trial_converted webhook — not from order_total alone.

• Paid start: first invoice is payable now. Send the plan's monthly (or yearly) price on the product line with billing_interval so this conversion books new MRR.
• Trial start: send order_total: 0 and product price: 0. Keep the plan code and subscription_id so the signup still counts as a conversion. Book MRR later with trial_converted when the trial becomes payable. Do not fire a second paid trackConversion on the same subscription to book MRR — later conversions are treated as renewals.

// Paid-from-day-one start. billing_interval + interval_count + the plan
// price on the product line are what mark this conversion as new MRR.
badgerlytics.trackConversion({
  // Use your real order / invoice id (not a timestamp) so a refreshed
  // success page or double-fire can be deduplicated downstream.
  order_id: '<your_order_or_invoice_id>',
  order_total: 15900,                  // cents
  customer_id: '<your_user_id>',
  subscription_id: '<your_subscription_id>',
  products: [
    {
      product_code: 'pro_monthly',
      name: 'Pro (Monthly)',
      price: 15900,
      quantity: 1,
      billing_interval: 'month',
      interval_count: 1,
      category: 'pro',
    },
  ],
});

// Trial start. Keep plan identity and subscription_id, but send $0 so
// this does not book MRR. When the trial becomes payable, forward
// trial_converted from your billing webhook (see Lifecycle events).
badgerlytics.trackConversion({
  order_id: '<your_order_or_checkout_id>',
  order_total: 0,
  customer_id: '<your_user_id>',
  subscription_id: '<your_subscription_id>',
  products: [
    {
      product_code: 'pro_monthly',
      name: 'Pro (Monthly)',
      price: 0,
      quantity: 1,
      billing_interval: 'month',
      interval_count: 1,
      category: 'pro',
    },
  ],
});

Conversion fires at signup. Everything after that — cancellations, upgrades, downgrades, renewals, and trial → paid — happens in your billing system. Forward each state change to us as a subscription_changeevent from your server, and we'll keep MRR, churn, expansion, contraction, and cancellation-reason reports accurate. For trials, the checkout conversion is $0; new MRR is the trial_converted event you send when the customer becomes payable.

Change types: cancel, upgrade, downgrade, renewal, reactivate, trial_started, and trial_converted. Any other value is rejected with a 400 at ingest, so typos surface immediately instead of silently skewing reports. Include a positive or negative mrr_delta_cents (an integer, in cents, normalized to a monthly value) matching the direction of the change (0 for plain renewals), and an ISO 8601 effective_at when the change takes effect later (e.g. a cancellation at period end).

Quick curl smoke test:

curl -X POST https://events.badgerlytics.com/ingestion-api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_secret_api_key>" \
  -d '{
    "property_id": "<your_property_id>",
    "event_type": "subscription_change",
    "unique_event_id": "<uuid-v4>",
    "session_id": "<server-side-session-uuid>",
    "visitor_id": "<server-side-visitor-uuid>",
    "event_time": "<ISO-8601-now>",
    "subscription_data": {
      "subscription_id": "<your_subscription_id>",
      "customer_id": "<your_user_id>",
      "change_type": "cancel",
      "mrr_delta_cents": -15900,
      "previous_plan_code": "pro_monthly",
      "currency": "USD",
      "cancel_reason": "too_expensive",
      "effective_at": "<ISO-8601-effective-date>"
    }
  }'

Stripe is one mapping of that payload. The app's SaaS Setup wizard generates this exact snippet pre-configured for your property:

// Cloudflare Worker / Vercel edge function — example adapter.
// Forwards Stripe customer.subscription.* webhooks as Badgerlytics
// subscription_change events. Set BADGERLYTICS_SECRET_KEY and
// PROPERTY_ID as environment variables.
//
// Before production:
//   - Verify the Stripe-Signature header before trusting the payload.
//   - Do not forward customer.subscription.created: a paid checkout's
//     trackConversion already books new MRR. Trials book MRR here via
//     trial_converted when status leaves trialing.

export default {
  async fetch(req, env) {
    const event = await req.json();
    const sub = event.data?.object || {};
    const prev = event.data?.previous_attributes || {};
    const prevItems = prev.items;

    // Monthly recurring value of a subscription in cents: quantity x
    // unit_amount, normalized by billing interval so a yearly plan
    // doesn't inflate MRR 12x.
    const mrrCents = (items) => {
      const item = items?.data?.[0];
      const price = item?.price || {};
      const amount = (price.unit_amount || 0) * (item?.quantity || 1);
      const count = price.recurring?.interval_count || 1;
      const divisor = price.recurring?.interval === 'year' ? 12 * count : count;
      return Math.round(amount / divisor);
    };

    const canceledDuringTrial = sub.status === 'trialing'
      || prev.status === 'trialing'
      || (
        !prev.status
        && Number(sub.trial_end) > 0
        && Number(sub.canceled_at) > 0
        && Number(sub.canceled_at) <= Number(sub.trial_end) + 120
      );
    const becamePayable = prev.status === 'trialing'
      && (sub.status === 'active' || sub.status === 'past_due');

    let change_type;
    let mrr_delta_cents;
    let unique_event_id = crypto.randomUUID();
    if (event.type === 'customer.subscription.deleted') {
      // Never became payable — no churned MRR to book.
      if (canceledDuringTrial) return new Response(null, { status: 204 });
      change_type = 'cancel';
      mrr_delta_cents = -mrrCents(sub.items);
    } else if (event.type === 'customer.subscription.updated' && becamePayable) {
      change_type = 'trial_converted';
      mrr_delta_cents = mrrCents(sub.items);
      unique_event_id = 'saas:trial_converted:' + String(sub.id || '');
    } else if (event.type === 'customer.subscription.updated' && prevItems) {
      const current = mrrCents(sub.items);
      const previous = mrrCents(prevItems);
      if (current === previous) return new Response(null, { status: 204 });
      change_type = current > previous ? 'upgrade' : 'downgrade';
      mrr_delta_cents = current - previous;
    } else {
      return new Response(null, { status: 204 });
    }

    const body = {
      property_id: env.PROPERTY_ID,
      event_type: 'subscription_change',
      unique_event_id,
      session_id: 'srv_' + crypto.randomUUID(),
      visitor_id: 'srv_' + (sub.customer || 'unknown'),
      event_time: new Date().toISOString(),
      customer_id: String(sub.customer || ''),
      subscription_data: {
        subscription_id: String(sub.id || ''),
        customer_id: String(sub.customer || ''),
        change_type,
        mrr_delta_cents,
        previous_plan_code: prevItems?.data?.[0]?.price?.lookup_key
          || sub.items?.data?.[0]?.price?.lookup_key || '',
        new_plan_code: sub.items?.data?.[0]?.price?.lookup_key || '',
        currency: (sub.currency || 'usd').toUpperCase(),
        cancel_reason: sub.cancellation_details?.reason || '',
        effective_at: new Date().toISOString(),
      },
    };

    const res = await fetch('https://events.badgerlytics.com/ingestion-api/events', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer ' + env.BADGERLYTICS_SECRET_KEY,
      },
      body: JSON.stringify(body),
    });

    if (!res.ok) {
      // Non-2xx makes Stripe retry the webhook later instead of losing it.
      return new Response('forward failed', { status: 500 });
    }
    return new Response('ok', { status: 200 });
  },
};