Next.js — Server tracking

Track events from the server so they appear in the same session as client events. Use your shared signal client and pass sessionId and windowId from request headers into every signal.capture() or signal.identify() call.

App Router: API routes

Use getSessionInfo(request) with the route’s Request:

// app/api/checkout/route.ts
import { signal, getSessionInfo } from '@/lib/signal-server';
import { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  const { sessionId, windowId, distinctId } = getSessionInfo(request);
  const body = await request.json();

  const orderId = await processOrder(body);

  signal.capture({
    distinctId: distinctId || body.userId,
    event: 'order_processed',
    properties: { orderId, amount: body.amount },
    sessionId,
    windowId,
  });

  return Response.json({ success: true, orderId });
}

App Router: Server Actions

Read headers with headers() from next/headers and pass the same identifiers:

// app/actions.ts
'use server';

import { signal } from '@/lib/signal-server';
import { headers } from 'next/headers';

export async function processOrderAction(orderData: OrderData) {
  const headersList = headers();
  const sessionId = headersList.get('x-signal-session-id') || undefined;
  const windowId = headersList.get('x-signal-window-id') || undefined;
  const distinctId = headersList.get('x-signal-distinct-id') || undefined;

  const orderId = await processOrder(orderData);

  signal.capture({
    distinctId: distinctId || orderData.userId,
    event: 'order_processed',
    properties: { orderId, amount: orderData.amount },
    sessionId,
    windowId,
  });

  return { success: true, orderId };
}

Pages Router: API routes

Use req.headers and a small helper:

// pages/api/orders.ts
import { NextApiRequest, NextApiResponse } from 'next';
import { signal } from '@/lib/signal-server';

function getSessionInfo(req: NextApiRequest) {
  return {
    sessionId: req.headers['x-signal-session-id'] as string | undefined,
    windowId: req.headers['x-signal-window-id'] as string | undefined,
    distinctId: req.headers['x-signal-distinct-id'] as string | undefined,
  };
}

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const { sessionId, windowId, distinctId } = getSessionInfo(req);

  const orderId = await processOrder(req.body);

  signal.capture({
    distinctId: distinctId || req.body.userId,
    event: 'order_created',
    properties: { orderId },
    sessionId,
    windowId,
  });

  res.json({ success: true, orderId });
}

Pages Router: getServerSideProps

Read headers from context.req and pass them into signal.capture():

// pages/dashboard.tsx
import { GetServerSideProps } from 'next';
import { signal } from '@/lib/signal-server';

export const getServerSideProps: GetServerSideProps = async (context) => {
  const sessionId = context.req.headers['x-signal-session-id'] as string | undefined;
  const windowId = context.req.headers['x-signal-window-id'] as string | undefined;
  const distinctId = context.req.headers['x-signal-distinct-id'] as string | undefined;

  signal.capture({
    distinctId: distinctId || 'anonymous',
    event: '$pageview',
    properties: { path: context.resolvedUrl },
    sessionId,
    windowId,
  });

  return { props: {} };
};

Enabling tracing headers on the client

For the server to receive x-signal-session-id, x-signal-window-id, and x-signal-distinct-id, the client must send them. Set addTracingHeaders: true (or an array of hostnames) in your SignalNextProvider options when you use server-side tracking. See Configuration.

Advanced server helpers

The server package also exports:

trackServerEvent(options) — Convenience that uses the singleton from createSignalServer to capture one event (e.g. in a one-off handler). Options: distinctId, event, properties.
getSignalServerSideProps(getServerSidePropsFunc, options) — Wraps your getServerSideProps to inject Signal props (e.g. distinctId, sessionId) from getDistinctId / getSessionId callbacks. Use when you want Signal context in page props.
withSignalConfig(nextConfig) — Wraps your Next.js config to inject Signal env vars (NEXT_PUBLIC_SIGNAL_ENDPOINT, NEXT_PUBLIC_SIGNAL_PROJECT_ID). Use if you prefer config over .env.local.

Getting Started

Features

Integrations

Server tracking

Next.js — Server tracking

App Router: API routes

App Router: Server Actions

Pages Router: API routes

Pages Router: getServerSideProps

Enabling tracing headers on the client

Advanced server helpers

See also

​Next.js — Server tracking

​App Router: API routes

​App Router: Server Actions

​Pages Router: API routes

​Pages Router: getServerSideProps

​Enabling tracing headers on the client

​Advanced server helpers

​See also

Next.js — Server tracking

App Router: API routes

App Router: Server Actions

Pages Router: API routes

Pages Router: getServerSideProps

Enabling tracing headers on the client

Advanced server helpers

See also