Agentic IntelligenceA teammate that investigates your data, uncover what matters and deliver reports and actions for your team to approve.Meet the agents

Getting Started

SDK Quickstart

Get Flowgrid tracking in your app in under 5 minutes. Pick the path that fits your stack — script tag for zero-build sites, or the npm SDK for typed, full-feature access in any JS runtime.

The package is published on npm: npmjs.com/package/flowgrid-sdk.

Let your AI assistant set it up

Copy the prompt into the assistant or coding agent you build with. It installs flowgrid-sdkwith your package manager (npm, pnpm, bun or yarn), or the CDN script tag where there's no build step, and identifies signed-in users.

Open in Claude

Paste it into Claude Code in your project, or into claude.ai.

Set up Flowgrid analytics (https://flow-grid.xyz) on my website. If you can see my code (Claude Code, or a repo I've attached), make the changes; if not, tell me exactly what to paste and where.

My Flowgrid Website ID and API key: don't ask me for them, and never write them into code or into this chat.
- In a codebase, read them from public environment variables — NEXT_PUBLIC_FLOWGRID_WEB_ID and NEXT_PUBLIC_FLOWGRID_API_KEY (or the framework's own public prefix, e.g. VITE_FLOWGRID_WEB_ID). Add the names to the env example file and tell me which file to put the values in; I'll paste them myself from Flowgrid (Dashboard → my website).
- Where there is no codebase (a CMS head snippet), keep the placeholders YOUR_WEBSITE_ID and YOUR_API_KEY exactly as written and tell me where to replace them.

1. Find out what my website is built with (read package.json and the lockfile, or ask me which CMS) and tell me before changing anything.

2. Install the Flowgrid SDK (https://www.npmjs.com/package/flowgrid-sdk) with the package manager the project already uses — match the lockfile:
- package-lock.json: npm install flowgrid-sdk
- pnpm-lock.yaml: pnpm add flowgrid-sdk
- bun.lock or bun.lockb: bun add flowgrid-sdk
- yarn.lock: yarn add flowgrid-sdk

3. Start it once, for the whole app:
- Next.js: in the root layout, wrap {children} in <FlowgridProvider webId={process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID} apiKey={process.env.NEXT_PUBLIC_FLOWGRID_API_KEY}> imported from "flowgrid-sdk/next".
- React (Vite, Lovable, Bolt): the same <FlowgridProvider>, imported from "flowgrid-sdk/react", around the app in the entry file.
- Any other JavaScript app (Vue, Svelte, plain TS): call Flowgrid.init({ webId, apiKey }) once in the entry file, imported from "flowgrid-sdk".
- No build step (plain HTML, or a CMS like WordPress, Webflow, Shopify, Framer): skip the install and put this tag once in <head> instead:
<script src="https://cdn.flow-grid.xyz/flowgrid.min.js" data-site="YOUR_WEBSITE_ID" data-api-key="YOUR_API_KEY"></script>
Pageviews, sessions, page changes in single-page apps, Core Web Vitals, heatmaps and traffic sources are then tracked automatically. Don't add manual page-view calls.

4. If the website has sign-in, identify the signed-in user once the session is known:
- React or Next.js: render <FlowgridUser id={user.id} traits={{ email: user.email, name: user.name }} /> (same import as the provider) inside the provider. For a next-auth, Clerk or Supabase session, <FlowgridUser from={session} /> works too.
- Script tag: window.FlowGrid && window.FlowGrid.identify(user.id, { email: user.email, name: user.name });

5. Custom events, only where I ask for them: Flowgrid.instance()?.track("event_name", { ...properties }) (Flowgrid from "flowgrid-sdk"), or window.FlowGrid.track(...) with the script tag. Feature flags: useFlag("flag-key") from the same React import.

6. Tell me how to check it works: tracking is off on localhost by design, so deploy or open a preview URL, browse a page, and confirm requests to core.flow-grid.xyz in the browser's network tab and a live visitor in the Flowgrid dashboard.

Forms: the SDK doesn't capture forms. If I give you a form ID, follow the forms step at https://flow-grid.xyz/documentation/create-form-events instead of inventing one.

Rules: use only the Flowgrid APIs above or in https://flow-grid.xyz/documentation — never guess a method name. Don't add or remove other analytics tools. Keep the change small and explain each edit.

Option A — Script tag no build step

Paste one tag in your <head>. Flowgrid auto-tracks pageviews, SPA navigation, sessions, scroll depth, performance (Core Web Vitals), heatmaps, and attribution immediately.

index.html

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

Where to find your IDs

Open your Dashboard and select your site. Your data-site (Website ID) and data-api-key(API key) are shown alongside your connected site. Paste both into the snippet above and you're live.

The global FlowGrid object is available for custom events:

custom-events.html

<script>
  FlowGrid.track("signup_clicked", { placement: "hero" });
  FlowGrid.identify("user_123", { plan: "pro", email: "alice@example.com" });
  FlowGrid.track("product_view", { productId: "sku_1", name: "T-Shirt", price: 29 });
  FlowGrid.track("add_to_cart", { productId: "sku_1", name: "T-Shirt", price: 29, quantity: 1 });
</script>

Localhost

Events are blocked on localhost

Option B — npm SDK TypeScript · any runtime

Works in React, Vue, Next.js, Svelte, Node, Cloudflare Workers, Vercel Edge — anywhere with fetch. Zero peer dependencies, Node >= 18.12.

Install the package

npm install flowgrid-sdk

Create a shared instance

Call FlowGrid.init() once — in your app entry point or a dedicated lib file — then import the result everywhere.

lib/flowgrid.ts

import { FlowGrid } from "flowgrid-sdk";

export const fg = FlowGrid.init({
  webId: process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID!,
  apiKey: process.env.NEXT_PUBLIC_FLOWGRID_API_KEY!,
  autoTrack: {
    replay:      true,  // session replay
    engagement:  true,  // scroll depth, time on page, idle detection
    performance: true,  // Core Web Vitals
  },
});

Environment variables

Store your IDs as NEXT_PUBLIC_FLOWGRID_WEB_ID and NEXT_PUBLIC_FLOWGRID_API_KEY. Never hard-code credentials in source.

Track your first event

app/page.tsx

import { fg } from "@/lib/flowgrid";

// Record a signup: identifies the user, fills the "Signed up" stage and counts them as active.
fg.trackAuth({ event: "signup", userId: "u_123", email: "alice@example.com", method: "google" });

That's it — you're tracking. Read on for events, identification, ecommerce, and more.

Track events

fg.track(eventName, properties) handles everything. Use any string for custom events. Certain well-known names are automatically routed to the correct feature module.

events.ts

import { fg } from "@/lib/flowgrid";

// Custom events — any name works
await fg.track("cta_clicked",     { placement: "hero" });
await fg.track("filter_applied",  { filter: "size", value: "L" });
await fg.track("video_played",    { videoId: "intro", duration: 120 });

// Named events routed to feature modules
await fg.track("feature_used",    { featureId: "export", featureName: "Data Export", userId: "u_1" });
await fg.track("add_to_cart",     { productId: "sku_1", name: "T-Shirt", price: 29, currency: "USD", quantity: 1 });
await fg.track("purchase",        { orderId: "ord_1", total: 49.99, currency: "USD", items: [] });

// Acquisition — one-liners for signup/login (see the Signups & Logins guide)
fg.signup("u_1", "google");       // → Acquisition Funnel "Signed up"
fg.login("u_1", "google");        // → returning-user / Logins tile

Identify users

Call setUser wherever your app knows who is signed in, on every page load. Every event from then on belongs to that person, and the traits you pass feed feature flag rules.

auth.ts

import { fg } from "@/lib/flowgrid";

fg.setUser(user.id, {
  email:   user.email,
  plan:    user.plan,
  company: user.company,
});

// On sign-out
fg.setUser(null);

Sign-ins that complete on your server use trackAuth there instead. See Identify users.

All namespaces

Every namespace is a lazy property — zero overhead until accessed. Use them for strongly-typed, module-specific APIs instead of track().

Group	Namespaces
Core	activation, features, prompts, flags
Analytics	pageViews, sessions, events, identify, heatmaps, performance, replay
Growth	funnels, multiPathFunnels, retention, attribution, subscriptions
Enterprise	engagement, cohorts, churn, monetization, support, acquisition, paths, alerts, security, forecasting

Feature Usage guide Signups & Logins guide Revenue attribution guide A/B Experiments guide

Session replay

Enabled by autoTrack.replay: true in your init config (shown above). Records DOM/scroll/click events via rrweb and sends sequenced chunks to your dashboard. No extra code needed — toggle the sample rate and input masking to tune it.

replay-options.ts

FlowGrid.init({
  webId: "...", apiKey: "...",
  autoTrack: {
    replay: { sampleRate: 0.25, maskAllInputs: true }, // tune it
    // replay: false,  // or opt out entirely
  },
});

Server-side & edge

Use the dedicated flowgrid-sdk/server entry point — a Node/edge-safe client for identity, feature usage and API / server error tracking. Works in Node ≥ 18, Bun, Deno, Cloudflare Workers, Vercel Edge — anywhere with fetch.

app/api/auth/callback/route.ts

import { FlowGridServer } from "flowgrid-sdk/server";

const fg = FlowGridServer.init({
  webId:  process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID!,
  apiKey: process.env.FLOWGRID_API_KEY!, // private key — server env only
});

// Identity from a server auth flow: identify + login event + DAU ping.
await fg.trackAuth({ event: "login", userId: user.id, email: user.email });

// Feature usage from an API route.
await fg.trackFeature({ featureId: "csv_export", featureName: "CSV Export", userId: user.id });

// Server error tracking with endpoint context.
await fg.trackError(err, { route: "/api/export", method: "POST", statusCode: 500 });

Full guide — auth events, linking the web session via visitorIdFromCookies(), defineFeature, error wrapping and delivery guarantees — on the Server-Side Tracking page.

PreviousIntroduction Next Server-Side Tracking

On this page

Set up with AI
Option A — Script tag
Option B — npm SDK
Track events
Identify users
All namespaces
Session replay
Cookie consent
Server-side & edge

Getting Started

Flowgrid Agent

Tracking Campaigns

Features

Installation Guides

Custom Integrations

SDK Quickstart

Let your AI assistant set it up

Option A — Script tag no build step

Option B — npm SDK TypeScript · any runtime

Install the package

Create a shared instance

Track your first event

Track events

Identify users

All namespaces

Session replay

Server-side & edge

Getting Started

Flowgrid Agent

Tracking Campaigns

Features

Installation Guides

Custom Integrations

SDK Quickstart

Let your AI assistant set it up

Option A — Script tag no build step

Option B — npm SDK TypeScript · any runtime

Install the package

Create a shared instance

Track your first event

Track events

Identify users

All namespaces

Session replay

Cookie consent

Server-side & edge