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.

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://core.flow-grid.xyz/flowgrid.js"
  data-site="YOUR_WEBSITE_ID"
  project-id="YOUR_PROJECT_ID"
  defer
></script>

Where to find your IDs

Open your Dashboardand select your project. Under the project name you'll see a Project ID chip — click it to copy your project-id. Your data-site(Website ID) is 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.productView({ productId: "sku_1", name: "T-Shirt", price: 29 });
  FlowGrid.addToCart({ productId: "sku_1", name: "T-Shirt", price: 29 }, 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";

await fg.track("signup_completed", { plan: "pro" });
fg.identifyUser("u_123", { plan: "pro", email: "alice@example.com" });

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: [] });

Identify users

Call identifyUser after sign-in. All subsequent events from that session are attributed to this user in your dashboard.

auth.ts

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

fg.identifyUser("u_123", {
  email:     "alice@example.com",
  plan:      "pro",
  company:   "Acme Corp",
  createdAt: "2024-01-15",
});

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, experiments
Analytics	pageViews, sessions, events, identify, heatmaps, performance, replay
Ecommerce	products, cart, checkout, purchases, refunds, promotions, wishlist, ltv, search, subscriptions
Enterprise	engagement, cohorts, churn, monetization, support, acquisition, paths, security, forecasting

Feature Usage guide →Ecommerce 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

Works in Node, Bun, Deno, Cloudflare Workers, Vercel Edge — anywhere with fetch. Construct an instance directly on the server.

app/api/track/route.ts

import { FlowGrid } from "flowgrid-sdk";

const fg = new FlowGrid(
  process.env.FLOWGRID_WEB_ID!,
  "https://core.flow-grid.xyz",
  process.env.FLOWGRID_API_KEY!,
);

export async function POST(req: Request) {
  const { userId, event } = await req.json();
  await fg.events.track({ eventName: event, properties: { userId } });
  return Response.json({ ok: true });
}

PreviousIntroduction Next Feature Usage

On this page

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