Connecting Uniform Context Plugins

Last updated: June 22, 2026

Summary

Uniform Context plugins add debugging (Context DevTools), analytics forwarding (Google Analytics), and real-time personalization/test reporting (Uniform Insights) to your app. This guide shows how to connect them in a CSK v6 Next.js app router project.

Create the Uniform client context component

Create src/utils/clientContext.tsx — plugins are registered here:

'use client';

import {
  ClientContextComponent,
  createClientUniformContext,
  useInitUniformContext,
} from '@uniformdev/canvas-next-rsc/component';
import { ContextPlugin } from '@uniformdev/context';

export const UniformClientContext: ClientContextComponent = ({ manifest }) => {
  useInitUniformContext(() => {
    const plugins: ContextPlugin[] = [];

    return createClientUniformContext({
      manifest,
      plugins,
      defaultConsent: true,
    });
  });

  return null;
};

Connect it to UniformContext as the clientContextComponent in src/app/layout.tsx:

import { UniformContext } from '@uniformdev/canvas-next-rsc';
import { UniformClientContext } from '@/utils/clientContext';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <UniformContext clientContextComponent={UniformClientContext}>{children}</UniformContext>
      </body>
    </html>
  );
}

How to enable plugins:

1. Connect Context DevTools

Exposes visitor classification data to Context DevTools. Import the plugin and the useRouter hook:

import { useRouter } from 'next/navigation';
import { enableContextDevTools } from '@uniformdev/context';

Call const router = useRouter(); inside the component, then register the plugin:

plugins.push(
  enableContextDevTools({
    onAfterMessageReceived: () => {
      router.refresh();
    },
  })
);

2. Connect the Google Analytics plugin

Sends personalization and testing data to Google Analytics. If your app doesn't already use the Global Site Tag (gtag.js), add the script — it must be the first script after </head>.

Install the package, import, and register:

npm install @uniformdev/context-gtag

import { enableGoogleGtagAnalytics } from '@uniformdev/context-gtag';

plugins.push(enableGoogleGtagAnalytics());

3. Connect Uniform Insights

Reports how personalization and A/B tests perform in real time. Add environment variables:

# endpoint URL copied from the Insights settings page
UNIFORM_INSIGHTS_ENDPOINT = 'your endpoint url'

# API key provided by your Uniform account manager
UNIFORM_INSIGHTS_KEY = 'your api key'

Import enableUniformInsights from @uniformdev/context and register it (client-side):

plugins.push(
  enableUniformInsights({
    endpoint: {
      type: 'proxy',
      path: '/api/analytics',
    },
  })
);

Add a proxy route at src/app/api/analytics/route.ts to forward events to the Insights ingestion endpoint:

import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  if (!process.env.UNIFORM_INSIGHTS_ENDPOINT || !process.env.UNIFORM_INSIGHTS_KEY) {
    throw Error('Check Uniform Insights connection settings');
  }
  const destination = new URL(process.env.UNIFORM_INSIGHTS_ENDPOINT);
  destination.pathname = '/v0/events';
  destination.searchParams.set('name', 'analytics_events');

  const data = await req.json();
  const response = await fetch(destination.toString(), {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.UNIFORM_INSIGHTS_KEY,
    },
    body: JSON.stringify(data),
  });

  const ingestionResponse = await response.json();
  return NextResponse.json(ingestionResponse, { status: response.status });
}

Combine plugins as needed

Activate only the plugins you need. Complete clientContext.tsx with all three:

'use client';

import { useRouter } from 'next/navigation';
import {
  ClientContextComponent,
  createClientUniformContext,
  useInitUniformContext,
} from '@uniformdev/canvas-next-rsc/component';
import { ContextPlugin, enableContextDevTools, enableUniformInsights } from '@uniformdev/context';
import { enableGoogleGtagAnalytics } from '@uniformdev/context-gtag';

export const UniformClientContext: ClientContextComponent = ({ manifest }) => {
  const router = useRouter();
  useInitUniformContext(() => {
    const plugins: ContextPlugin[] = [];

    plugins.push(
      enableContextDevTools({
        onAfterMessageReceived: () => {
          router.refresh();
        },
      })
    );

    plugins.push(enableGoogleGtagAnalytics());

    plugins.push(
      enableUniformInsights({
        endpoint: {
          type: 'proxy',
          path: '/api/analytics',
        },
      })
    );

    return createClientUniformContext({
      manifest,
      plugins,
      defaultConsent: true,
    });
  });

  return null;
};

Troubleshooting

Verify it works: run the app — Context DevTools shows visitor classification data, GA receives personalization/testing events, and POSTs to /api/analytics return a successful ingestion response.

DevTools data not updating after classification changes: confirm onAfterMessageReceived calls router.refresh() and the component runs client-side ('use client').