Next.js app

This page builds a Next.js App Router app with two packages. Grain Tag (@grainql/tag) runs in the browser for page views, clicks, heatmaps, and the user ID. Analytics Web (@grainql/analytics-web) runs on the server with the SERVER_SIDE strategy. Each block names its package. For the Pages Router, read Next.js.

npm install @grainql/tag @grainql/analytics-web

Environment variables

Put these in .env.local. Next.js sends every NEXT_PUBLIC_ variable to the browser. The secret key has no prefix, so it stays on the server.

NEXT_PUBLIC_GRAIN_TENANT_ID=your-tenant-id
GRAIN_TENANT_ID=your-tenant-id
GRAIN_SECRET_KEY=$GRAIN_SECRET_KEY

Do not put the secret key in a NEXT_PUBLIC_ variable. Anyone who opens the site can read it.

Grain Tag in the root layout

Grain Tag runs in the browser. A Client Component calls init one time. init returns a no-op stub outside a browser, so the import is safe in a server render.

// app/grain.tsx
'use client';

import { useEffect } from 'react';
import { init, isInitialized } from '@grainql/tag';

export function GrainAnalytics() {
  useEffect(() => {
    if (!isInitialized()) {
      init({ tenantId: process.env.NEXT_PUBLIC_GRAIN_TENANT_ID! });
    }
  }, []);
  return null;
}

// app/layout.tsx
import { GrainAnalytics } from './grain';
import { AuthSync } from './auth-sync';
import { SessionProvider } from 'next-auth/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SessionProvider>
          <GrainAnalytics />
          <AuthSync />
          {children}
        </SessionProvider>
      </body>
    </html>
  );
}

Route changes

Grain Tag (@grainql/tag) tracks the first page view and every App Router navigation. The App Router navigates through the History API, so a route change needs no component. If you set enablePageViews: false in init and track page views yourself, read the path from usePathname.

// app/route-tracker.tsx
'use client';

import { useEffect } from 'react';
import { usePathname } from 'next/navigation';
import { track } from '@grainql/tag';

export function RouteTracker() {
  const pathname = usePathname();

  useEffect(() => {
    track('page_viewed', { page: pathname });
  }, [pathname]);

  return null;
}

Identify with NextAuth

Grain Tag (@grainql/tag) attaches the user ID to every later event after identify. Read the session from NextAuth and call identify when it holds a user. Grain Tag has no method that clears the user ID.

// app/auth-sync.tsx
'use client';

import { useEffect } from 'react';
import { useSession } from 'next-auth/react';
import { identify } from '@grainql/tag';

export function AuthSync() {
  const { data: session } = useSession();

  useEffect(() => {
    if (session?.user?.id) {
      identify(session.user.id);
    }
  }, [session]);

  return null;
}

identify called before init is queued and replayed after initialization. Read Identify users.

A client event

Call track from a Client Component.

// app/page.tsx
'use client';

import { track } from '@grainql/tag';

export default function HomePage() {
  return (
    <button onClick={() => track('cta_clicked', { location: 'hero' })}>Get Started</button>
  );
}

A server-side event

A route handler uses Analytics Web (@grainql/analytics-web) with the SERVER_SIDE strategy and the secret key. Create the client one time at module scope. The { flush: true } option sends the event before the function returns. Without it, a serverless function can stop before the batch timer fires, and the event is lost. The userId field of the event object attaches the event to the user who placed the order.

// app/api/orders/route.ts
import { createGrainAnalytics } from '@grainql/analytics-web';
import { auth } from '@/auth';

const grain = createGrainAnalytics({
  tenantId: process.env.GRAIN_TENANT_ID!,
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY!
});

export async function POST(request: Request) {
  const session = await auth();
  const order = await request.json();

  await grain.track(
    {
      eventName: 'purchase',
      userId: session?.user?.id,
      properties: {
        orderId: order.id,
        total: order.total,
        currency: order.currency
      }
    },
    { flush: true }
  );

  return Response.json({ ok: true });
}

auth is the NextAuth helper of your app. Read Node.js and servers and Authentication.

Apps

Query API

Environment variables

Grain Tag in the root layout

Route changes

Identify with NextAuth

A client event

A server-side event

​Environment variables

​Grain Tag in the root layout

​Route changes

​Identify with NextAuth

​A client event

​A server-side event

Environment variables

Grain Tag in the root layout

Route changes

Identify with NextAuth

A client event

A server-side event