FlowgridDocs
Dashboard

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.

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
1<script 2 src="https://cdn.flow-grid.xyz/flowgrid.min.js" 3 data-site="YOUR_WEBSITE_ID" 4 data-api-key="YOUR_API_KEY" 5></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
1<script> 2 FlowGrid.track("signup_clicked", { placement: "hero" }); 3 FlowGrid.identify("user_123", { plan: "pro", email: "alice@example.com" }); 4 FlowGrid.productView({ productId: "sku_1", name: "T-Shirt", price: 29 }); 5 FlowGrid.addToCart({ productId: "sku_1", name: "T-Shirt", price: 29 }, 1); 6</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.

1

Install the package

1npm install flowgrid-sdk
2

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
1import { FlowGrid } from "flowgrid-sdk"; 2 3export const fg = FlowGrid.init({ 4 webId: process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID!, 5 apiKey: process.env.NEXT_PUBLIC_FLOWGRID_API_KEY!, 6 autoTrack: { 7 replay: true, // session replay 8 engagement: true, // scroll depth, time on page, idle detection 9 performance: true, // Core Web Vitals 10 }, 11});

Environment variables

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

3

Track your first event

app/page.tsx
1import { fg } from "@/lib/flowgrid"; 2 3// Record a signup — populates your Acquisition Funnel "Signed up" stage. 4fg.signup("u_123", "google"); 5fg.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
1import { fg } from "@/lib/flowgrid"; 2 3// Custom events — any name works 4await fg.track("cta_clicked", { placement: "hero" }); 5await fg.track("filter_applied", { filter: "size", value: "L" }); 6await fg.track("video_played", { videoId: "intro", duration: 120 }); 7 8// Named events routed to feature modules 9await fg.track("feature_used", { featureId: "export", featureName: "Data Export", userId: "u_1" }); 10await fg.track("add_to_cart", { productId: "sku_1", name: "T-Shirt", price: 29, currency: "USD", quantity: 1 }); 11await fg.track("purchase", { orderId: "ord_1", total: 49.99, currency: "USD", items: [] }); 12 13// Acquisition — one-liners for signup/login (see the Signups & Logins guide) 14fg.signup("u_1", "google"); // → Acquisition Funnel "Signed up" 15fg.login("u_1", "google"); // → returning-user / Logins tile

Identify users

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

auth.ts
1import { fg } from "@/lib/flowgrid"; 2 3fg.identifyUser("u_123", { 4 email: "alice@example.com", 5 plan: "pro", 6 company: "Acme Corp", 7 createdAt: "2024-01-15", 8});

All namespaces

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

GroupNamespaces
Coreactivation, features, prompts, experiments
AnalyticspageViews, sessions, events, identify, heatmaps, performance, replay
Ecommerceproducts, cart, checkout, purchases, refunds, promotions, wishlist, ltv, search, subscriptions
Enterpriseengagement, cohorts, churn, monetization, support, acquisition, paths, security, forecasting
Feature Usage guide →Signups & Logins 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
1FlowGrid.init({ 2 webId: "...", apiKey: "...", 3 autoTrack: { 4 replay: { sampleRate: 0.25, maskAllInputs: true }, // tune it 5 // replay: false, // or opt out entirely 6 }, 7});

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
1import { FlowGridServer } from "flowgrid-sdk/server"; 2 3const fg = FlowGridServer.init({ 4 webId: process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID!, 5 apiKey: process.env.FLOWGRID_API_KEY!, // private key — server env only 6}); 7 8// Identity from a server auth flow: identify + login event + DAU ping. 9await fg.trackAuth({ event: "login", userId: user.id, email: user.email }); 10 11// Feature usage from an API route. 12await fg.trackFeature({ featureId: "csv_export", featureName: "CSV Export", userId: user.id }); 13 14// Server error tracking with endpoint context. 15await 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.

PreviousIntroductionNext Server-Side Tracking