Next.js Integration | Flowgrid Documentation

Add the tracking script to app layout

Create your new website and add the following script tag preferably in the layout.jsx section:

Open your project's app/layout.jsx file.
Add the Flowgrid tracking script tag inside the head section:

layout.jsx

import Script from 'next/script';

export default function RootLayout({ children }) {
	return (
		<html lang="en">
			<head>
				<Script
					src="https://core.flow-grid.xyz/flowgrid.js"
					data-site="YOUR_WEBSITE_ID"
					data-api-key="YOUR_API_KEY"
					strategy="afterInteractive"
				/>
			</head>
			<body>{children}</body>
		</html>
	);
}
								

Use the npm SDK + drop-in helpers

Prefer typed, in-app tracking over the script tag? Install the SDK and use the built-in helpers so you never re-implement consent wiring or stable IDs by hand. Everything below is framework-agnostic — the helpers import directly fromflowgrid-sdk.

1. Install

terminal

npm install flowgrid-sdk
# or: pnpm add flowgrid-sdk / yarn add flowgrid-sdk

2. Create a single setup file

Initialise FlowGrid once and re-export the helpers. setupConsent creates a consent manager andkeeps FlowGrid's consent gates in sync automatically.

lib/flowgrid.ts

// lib/flowgrid.ts
import {
  FlowGrid,
  setupConsent,
  attachConsentBanner,
  getOrCreateAnonId,
  getOrCreateCartId,
} from "flowgrid-sdk";

// init() touches browser globals, so guard against SSR (window is undefined on the server).
const isClient = typeof window !== "undefined";

export const flowgrid = isClient
  ? FlowGrid.init({
      webId: process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID!,
      apiKey: process.env.NEXT_PUBLIC_FLOWGRID_API_KEY!,
      autoTrack: { performance: true, engagement: true, replay: true },
    })
  : null;

export const track = flowgrid?.track.bind(flowgrid) ?? (() => undefined);

// One call creates a consent manager AND keeps FlowGrid's consent gates in sync —
// no manual FlowGridTransport.setConsent() plumbing.
export const getConsent = () =>
  setupConsent({ cookieName: "my_app_consent", cookieDays: 180, respectDNT: true });

// Re-export the drop-in helpers so the rest of your app imports from one place.
export { attachConsentBanner, getOrCreateAnonId, getOrCreateCartId };

3. Cookie consent banner

Drop this client component into your app/layout.tsx. No manual transport sync — getConsent() did that for you.

components/cookie-banner.tsx

// components/cookie-banner.tsx
"use client";
import { useEffect, useState } from "react";
import { getConsent } from "@/lib/flowgrid";

export function CookieBanner() {
  const [manager, setManager] = useState<ReturnType<typeof getConsent>>();
  const [visible, setVisible] = useState(false);

  useEffect(() => {
    const cm = getConsent();            // already pushes stored prefs into FlowGrid
    setManager(cm);
    if (!cm.hasConsented()) setVisible(true);
  }, []);

  if (!visible) return null;

  return (
    <div id="cookie-banner" className="fixed bottom-0 inset-x-0 p-4 bg-background border-t">
      <button onClick={() => { manager?.rejectNonEssential(); setVisible(false); }}>
        Reject non-essential
      </button>
      <button onClick={() => { manager?.acceptAll(); setVisible(false); }}>
        Accept all
      </button>
    </div>
  );
}

Not using React for the banner?

Call attachConsentBanner() instead — it wires the#accept-btn /#reject-btn buttons inside any#cookie-banner element for you.

4. Track with stable IDs

getOrCreateAnonId() andgetOrCreateCartId() persist a stable visitor / cart id (SSR-safe), so cart and checkout events line up automatically.

anywhere.ts

import { track, flowgrid, getOrCreateAnonId, getOrCreateCartId } from "@/lib/flowgrid";

// Product page view — stable anonymous id, no boilerplate.
track("product_view", {
  productId: p.id, name: p.name, price: p.price, currency: "EUR",
  userId: getOrCreateAnonId(),
});

// Add to cart — every line in the session shares one cartId.
flowgrid?.cart.add(
  { productId: p.id, name: p.name, price: p.price },
  1,
  getOrCreateCartId(),
);

5. Run an A/B experiment

exposureAuto() resolves the assigned variant and the visitor id for you, and localConversion() logs the win — no user-id threading required.

hooks/use-experiment.ts

// hooks/use-experiment.ts
"use client";
import { useEffect, useState } from "react";
import { flowgrid } from "@/lib/flowgrid";

export function useExperiment(id: string, variants: { id: string; weight: number }[]) {
  const [variant, setVariant] = useState<string | null>(null);

  useEffect(() => {
    flowgrid?.experiments.init([{ id, variants }]).then(() => {
      setVariant(flowgrid!.experiments.variant(id));
      flowgrid!.experiments.exposureAuto(id); // resolves the variant + anon id for you
    });
  }, [id]);

  return {
    variant,
    convert: (metric: string, value = 1) =>
      flowgrid?.experiments.localConversion(id, metric, value),
  };
}

// Usage in a component:
// const { variant, convert } = useExperiment("hero_cta_copy", [
//   { id: "control", weight: 50 },
//   { id: "treatment", weight: 50 },
// ]);
// <Button onClick={() => convert("signup")}>{variant === "treatment" ? "Start Free Trial" : "Book a Demo"}</Button>

Verify installation

After adding the script do the following to verify that the installation was successful:

Open your website that you are now tracking in the browser.
Go to your dashboard, click on your website and click the go to website's dashboard to see if the incoming traffic are being tracked.

Getting Started

Tracking Campaigns

Features

Installation Guides

Custom Integrations

Getting Started With Next.js