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,
} 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 };

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() persists a stable visitor id (SSR-safe), so product and cart events from one visitor line up automatically. Revenue comes from your connected payment provider, not from browser events.

anywhere.ts

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

// Product 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 — a named event; build the funnel from it with no extra code.
track("add_to_cart", {
  productId: p.id, name: p.name, price: p.price, currency: "EUR", quantity: 1,
  userId: getOrCreateAnonId(),
});

// Revenue is NOT tracked from the browser: connect your payment provider
// (Website settings → Payments) and payments arrive from its webhook, already
// matched to this visitor. See /documentation/revenue-attribution.

5. Run an A/B experiment

Read an A/B test flag where the change renders. Reading it counts the visitor; the experiment compares the variants on the results you pick in the dashboard.

components/hero-cta.tsx

// components/hero-cta.tsx
"use client";
import { useFlagVariant } from "flowgrid-sdk/react";

export function HeroCta() {
  const variant = useFlagVariant("hero-cta"); // null while off or outside the test
  return <Button>{variant === "trial" ? "Start Free Trial" : "Book a Demo"}</Button>;
}

// Create the experiment in Product Analytics → Experiments and pick what
// decides it (a signup, a form, revenue). No conversion call needed.

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