Quickstart

Every method below boots the same SDK (@backstory/browser, about 14 KB gzipped). Replace pk_live_… with a key from Organization → SDK keys. In local development use pk_dev_local and point ingestUrl at http://localhost:8080/v1/ingest.

npm

npm install @backstory/browser

import { Backstory } from "@backstory/browser";

Backstory.init({
  projectKey: "pk_live_…",
  privacy: { mode: "strict" },
  environment: process.env.APP_ENV,
  release: process.env.RELEASE,
});

Use a project per product or site, environment for the deployment tier of that product, and release for the exact build. Sessions can be filtered by all three in the dashboard, so keep them out of routes and URLs.

React (Vite, CRA)

Initialize once at the module level of your entry file, before rendering:

import { Backstory } from "@backstory/browser";
import { createRoot } from "react-dom/client";

Backstory.init({ projectKey: import.meta.env.VITE_BACKSTORY_KEY });
createRoot(document.getElementById("root")!).render(<App />);

Next.js (App Router)

Create a client component and render it once in app/layout.tsx:

app/backstory.tsx

"use client";
import { useEffect } from "react";
import { Backstory } from "@backstory/browser";

export function BackstoryProvider() {
  useEffect(() => { Backstory.init({ projectKey: process.env.NEXT_PUBLIC_BACKSTORY_KEY! }); }, []);
  return null;
}

Route changes through the App Router are detected automatically (History API).

Vue and Nuxt

// plugins/backstory.client.ts (Nuxt) or main.ts (Vue)
import { Backstory } from "@backstory/browser";
export default defineNuxtPlugin(() => { Backstory.init({ projectKey: useRuntimeConfig().public.backstoryKey }); });

Angular

main.ts

import { Backstory } from "@backstory/browser";
Backstory.init({ projectKey: environment.backstoryKey });
bootstrapApplication(AppComponent, appConfig);

SvelteKit

src/hooks.client.ts

import { Backstory } from "@backstory/browser";
import { PUBLIC_BACKSTORY_KEY } from "$env/static/public";
Backstory.init({ projectKey: PUBLIC_BACKSTORY_KEY });

Identify users and track events

Backstory.identify("user_123", "Jane Doe");            // id and display name, both stored exactly as sent
Backstory.track("intake_form_submitted", { steps: 4 });
Backstory.track("checkout_failed", { reason: "declined" }, { severity: "error" });

See Custom events for the Custom events panel, severity, alerts, and recording triggers. Do not include secrets, payment data, or PHI in event properties.

Verify

Open your app, click around, then open the dashboard. The session appears within about ten seconds. With debug: true in the config, Backstory.getDebugState() shows the governor level, queued bytes, credits, and acknowledged chunk count.