Getting Started

Introduction SDK Quickstart Server-Side Tracking

Tracking Campaigns

Getting Started

Server-side tracking

Track from your backend with flowgrid-sdk/server — a Node/edge-safe client scoped to identity, feature usage, ecommerce & revenue and API / server error tracking. Same wire contract as the browser SDK, so server and browser events resolve to one identity in your dashboard.

Overview

Some of the most valuable events never happen in the browser: the OAuth callback that actually creates the account, the API route a feature runs through, the webhook that fails at 3am. FlowGridServer covers exactly that surface:

Identity — identify users, update traits, alias, reset on logout, and the auth-level events (signup / login / active-user) fired from server auth flows.
Feature usage — feature_usage events from API routes, background jobs and webhooks.
Revenue & subscriptions — purchases and refunds arrive from your connected payment provider; subscription MRR events are fired from your billing webhooks.
Errors — server exceptions as error_events with route / method / status context.

Runs anywhere fetch runs

No window, no document, no storage, no Node built-ins — only global fetch. Works in Node ≥ 18, Next.js API routes and middleware, Vercel serverless & edge, Cloudflare Workers, Bun and Deno.

Init — once per process

Initialise in a dedicated lib file and import the instance everywhere server-side.init() is idempotent — calling it twice returns the same instance.

lib/flowgrid.server.ts

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

export const fg = FlowGridServer.init({
  webId: process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID!, // same site id as the browser SDK
  apiKey: process.env.FLOWGRID_API_KEY!,           // PRIVATE key — server env only
  // environment: "production",                    // defaults to NODE_ENV
});

Key hygiene

The server client requires your private API key. Keep it in a server-only env var (no NEXT_PUBLIC_ prefix) — never ship it to the browser.

Identity & auth events

trackAuth() is the one-call path for server auth flows — it identifies the user (writing the identity store, so they appear as a Known visitor), fires the signup/login event, and marks them active for DAU/WAU/MAU:

app/api/auth/callback/route.ts

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

// In your OAuth callback / session endpoint, once the user is known:
await fg.trackAuth({
  event:  "login",              // or "signup"
  userId: user.id,
  email:  user.email,           // email + name make the identity resolvable
  name:   user.name,
  method: "google",
});

The individual operations are all available too — same semantics as the browser SDK:

identity.ts

await fg.identifyUser(user.id, { email: user.email, plan: "pro" });
await fg.updateTraits(user.id, { plan: "enterprise" });      // after an upgrade
await fg.aliasUser("old_id", user.id);                       // ID migrations
await fg.pingActiveUser(user.id, { email: user.email });     // DAU/WAU/MAU signal
await fg.signup(user.id, "google", "pricing");               // funnel "Signed up" stage
await fg.login(user.id, "google");                           // returning-user signal
await fg.logout(user.id);                                    // reset identity on sign-out

Link the web session

Server events need a visitor_id. When you have the request, pass the visitor's real browser id so the server event links to their web session — visitorIdFromCookies() reads it from the request cookies:

app/api/auth/callback/route.ts

import { cookies } from "next/headers";
import { visitorIdFromCookies } from "flowgrid-sdk/server";
import { fg } from "@/lib/flowgrid.server";

const visitorId = visitorIdFromCookies(await cookies());

await fg.trackAuth(
  { event: "signup", userId: user.id, email: user.email, method: "google" },
  { visitorId }, // ← anonymous browsing session → known user, linked
);

No cookie available?

In jobs and webhooks there's no request cookie. Omit visitorId and the client derives a stable synthetic visitor from the userId (fg_srv_<hash>), so a user's server events always attribute to one visitor. Fully anonymous events share a per-process visitor.

Feature usage

Features that run through an API — exports, imports, integrations, AI actions — are tracked where they actually execute. Events land in the same Feature Usage dashboards as browser events (see the Feature Usage guide).

app/api/export/route.ts

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

// Direct:
await fg.trackFeature({
  featureId:   "csv_export",
  featureName: "CSV Export",
  userId:      user.id,
  properties:  { rows: 12_000 },
});

// Or bind once and use semantic verbs (server twin of fg.defineFeature):
const csvExport = fg.defineFeature("csv_export", "CSV Export", { category: "reports" });
await csvExport.used({ userId: user.id, rows: 12_000 });
await csvExport.completed({ userId: user.id });
await csvExport.abandoned({ userId: user.id, reason: "timeout" });

Revenue & subscriptions

Purchases and refunds are not SDK calls. Connect your payment provider in Website settings → Payments and Flowgrid receives its webhook directly: money is recorded where it is confirmed, with its real amount and currency, and nothing in your code can drop or double-count it. See Revenue attribution for the setup.

What the SDK does own is the subscription / MRR lifecycle — one method, discriminated on event. These power the MRR and churn dashboards, and billing state lives on your server, so emit them from your billing webhooks:

app/api/webhooks/stripe/route.ts

// customer.subscription.created
await fg.trackSubscription({
  event: "start",           // "change" | "cancel" | "renew" | "trial_converted" | "trial_expired"
  subscriptionId: sub.id,
  userId,
  plan: "professional",
  mrr: { amount: 9900, currency: "USD" }, // smallest currency unit (cents)
  billingCycle: "monthly",
  trialDays: 14,
});

// customer.subscription.deleted
await fg.trackSubscription({
  event: "cancel",
  subscriptionId: sub.id,
  userId,
  reason: sub.cancellation_details?.reason ?? "unknown",
  lostMrr: { amount: 9900, currency: "USD" },
});

Revenue attribution — Stripe & Lemon Squeezy

A payment webhook arrives with no cookies — on its own, FlowGrid can only attach a purchase to a synthetic server visitor. To attribute revenue to the real visitor (their session, landing page, UTM campaign), the visitor and session ids must round-trip through the payment provider: embed them in the checkout's metadata when you create it, read them back in the webhook. Both FlowGrid trackers mirror the ids to cookies (visitor_id / session_id, npm SDK: fg_session_id) precisely so your checkout route can read them.

Leg 1 — embed the ids at checkout creation:

app/api/checkout/route.ts

import { cookies } from "next/headers";
import { checkoutAttributionFromCookies } from "flowgrid-sdk/server";

// Stripe — goes into the checkout session's metadata
const session = await stripe.checkout.sessions.create({
  line_items, mode: "payment", success_url, cancel_url,
  metadata: { ...checkoutAttributionFromCookies(await cookies()) },
  // adds: flowgrid_visitor_id + flowgrid_session_id
});

// Lemon Squeezy — goes into checkoutData.custom
const checkout = await createCheckout(storeId, variantId, {
  checkoutData: {
    custom: { ...checkoutAttributionFromCookies(await cookies()) },
  },
});

Creating the checkout from the browser instead? The browser SDK exposes the same keys: fg.checkoutAttribution() — POST them to your checkout endpoint alongside the price id.

Leg 2 — read them back.For payments, Flowgrid does this itself when the provider's webhook arrives: nothing to write. For subscription events you send from your own webhook, attributionFromMetadata() unwraps Stripe objects (.metadata) and Lemon Squeezy payloads (.meta.custom_data) automatically:

app/api/webhooks/stripe/route.ts

import { attributionFromMetadata } from "flowgrid-sdk/server";
import { fg } from "@/lib/flowgrid.server";

// customer.subscription.created
const { visitorId, sessionId } = attributionFromMetadata(event.data.object);

await fg.trackSubscription(
  { event: "start", subscriptionId, userId, plan, mrr },
  { visitorId, sessionId }, // ← the subscription joins the real visitor's journey
);

What this buys you

With the real visitorId + sessionId on the payment, revenue ties back to the exact session that produced it — the campaign, referrer and landing page — instead of appearing as unattributed server traffic.

API & server error tracking

Thrown values of any shape become error_events. Pass route / method / statusCode so the dashboard can break failures down per endpoint:

app/api/teams/route.ts

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

try {
  // …
} catch (err) {
  await fg.trackError(err, {
    route:      "/api/teams/edit/[teamId]",
    method:     "PATCH",
    statusCode: 500,
    userId:     user.id,
  });
  throw err;
}

Or wrap the whole handler — the error is tracked and rethrown unchanged, so your framework's error handling behaves exactly as before:

wrapped.ts

export const PATCH = fg.withErrorTracking(
  async (req: NextRequest) => { /* … */ },
  { route: "/api/teams/edit/[teamId]", method: "PATCH" },
);

// Opt-in process-level capture (Node only) — reports uncaughtException /
// unhandledRejection as fatal, observes only, never swallows:
const detach = fg.captureUncaught();

FlowGrid never reports itself

Internal notes (messages starting with [FlowGrid]) are filtered out before sending, so FlowGrid's own delivery hiccups never pollute your error analytics.

Delivery guarantees

Never throws. Every method resolves { ok, status?, reason? } — a tracking failure can never break your API route.
Retries. Network failures and 5xx responses retry with jittered exponential backoff (2 retries, 10s timeout by default — tunable in init).
Server context. Every event is stamped with _server: true, the runtime, and _environment (from NODE_ENV), so you can segment server vs. browser traffic.
Fire-and-forget friendly. Don't want to await? void fg.trackFeature(…) is safe — failures are debug-noted, never raised.

PreviousSDK Quickstart Next Feature Usage

On this page

Overview
Init
Identity & auth events
Link the web session
Feature usage
Revenue & subscriptions
Revenue attribution
Error tracking
Delivery guarantees
Consent & compliance

Getting Started

Tracking Campaigns

Features

Installation Guides

Custom Integrations

Server-side tracking

Overview

Init — once per process

Identity & auth events

Link the web session

Feature usage

Revenue & subscriptions

Revenue attribution — Stripe & Lemon Squeezy

API & server error tracking

Delivery guarantees

Consent & compliance