React.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:

Within your project's components folder create InitialScript.jsx file.
Open your project's app.jsx file then import the component above into your app router
Add the Flowgrid tracking script tag inside the head section:

import { useEffect } from 'react';

const InitialScript = () => {
	useEffect(() => {
		const script = document.createElement('script');
		script.src = 'https://core.flow-grid.xyz/flowgrid.js';
		script.async = true;
		script.setAttribute('data-site', 'YOUR_WEBSITE_ID');
		script.setAttribute('data-api-key', 'YOUR_API_KEY');
		document.head.appendChild(script);

		return () => {
			// Optional cleanup
			document.head.removeChild(script);
		};
	}, []);

	return null;
};

export default InitialScript;

Use the npm SDK + drop-in helpers

Want typed, in-app tracking instead of the script tag? Install the SDK and lean on the built-in helpers so you never re-implement consent wiring or stable IDs by hand. They import directly from flowgrid-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.

src/lib/flowgrid.ts

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

export const flowgrid = FlowGrid.init({
  // Vite env vars (use process.env.REACT_APP_* for Create React App).
  webId: import.meta.env.VITE_FLOWGRID_WEB_ID,
  apiKey: import.meta.env.VITE_FLOWGRID_API_KEY,
  autoTrack: { performance: true, engagement: true, replay: true },
});

export const track = flowgrid.track.bind(flowgrid);

// One call creates a consent manager AND keeps FlowGrid's consent gates in sync.
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

Mount this component near your app root. No manual transport sync — getConsent() handled it.

src/components/CookieBanner.tsx

// src/components/CookieBanner.tsx
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="cookie-banner">
      <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, so cart and checkout events line up automatically.

anywhere.ts

import { track, flowgrid, getOrCreateAnonId, getOrCreateCartId } 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 — 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.

src/hooks/useExperiment.ts

// src/hooks/useExperiment.ts
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 React.js or React Router