Connecting Uniform Plugins

Introduction

This guide demonstrates how to connect some of the most popular plugins using the CSK v6 app router as an example.

The Context DevTools plugin prompts the Uniform tracker to expose visitor classification data, which can then be displayed in Context DevTools.
The GA plugin enables the transfer of personalization and testing data to Google Analytics, enhancing the reach and depth of your analytics.
The Uniform Insights empowers marketers and growth specialists to better understand how their personalization and A/B tests perform within the context of content and experience management. It also helps identify new optimization opportunities and analyze visitor behavior in real-time.

Create Uniform Client Context component

As the first step, you need to create a simple component where you can later define the required plugins and connect it to the UniformContext.

To do this, create a clientContext.tsx file in the src/utils directory with the following content:

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

Then, connect it to the UniformContext as the clientContextComponent in the src/app/layout.tsx file:

import { ReactNode } from 'react'; import { ThemeProvider as NextThemeProvider } from 'next-themes'; import { UniformContext } from '@uniformdev/canvas-next-rsc'; import '@/styles/globals.css'; import '@/styles/colors.css'; import '@/styles/dimensions.css'; import '@/styles/fonts.css'; import '@/styles/borders.css'; import { customFontVariables } from '@/fonts'; import { UniformClientContext } from '@/utils/clientContext'; export default function RootLayout({ children }: { children: ReactNode }) { return ( <html lang="en" suppressHydrationWarning> <body className={customFontVariables}> <NextThemeProvider attribute="class" defaultTheme="light" enableSystem> <UniformContext clientContextComponent={UniformClientContext}>{children}</UniformContext> </NextThemeProvider> </body> </html> ); }

Connecting Context DevTools

The Context DevTools plugin enables the Uniform tracker to expose visitor classification data, which can then be displayed in Context DevTools. For detailed instructions on setup and usage, refer to the Context DevTools guide.

To achieve this, you need to import the plugin in the relevant section, as well as the useRouter hook to ensure it functions correctly:

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

Next, integrate the plugin by initializing it and passing it to the plugin variable:

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

The complete clientContext.ts file is provided below:

'use client'; import { useRouter } from 'next/navigation'; import { ClientContextComponent, createClientUniformContext, useInitUniformContext, } from '@uniformdev/canvas-next-rsc/component'; import { ContextPlugin, enableContextDevTools } from '@uniformdev/context'; export const UniformClientContext: ClientContextComponent = ({ manifest }) => { const router = useRouter(); useInitUniformContext(() => { const plugins: ContextPlugin[] = []; plugins.push( enableContextDevTools({ onAfterMessageReceived: () => { router.refresh(); }, }) ); return createClientUniformContext({ manifest, plugins, defaultConsent: true, }); }); return null; };

Connecting GA plugin

Uniform enables you to add personalization and testing capabilities to your applications. Google Analytics is a popular tool for collecting and reporting activity within your application. Uniform can transmit personalization and testing data to Google Analytics, enhancing the scope and depth of your analytics. For more information, refer to the resources available here.

If your application doesn’t already use the Google Analytics Global Site Tag (gtag.js), you need to add the script.

About This Step
In a web application, the Global Site Tag should be added immediately after the closing <head> tag. It must be the first script following </Head>.

Add the following npm packages to your frontend application:

npm install @uniformdev/context-gtag

Then you need to add the plugin import in the import section:

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

Next, integrate the plugin by initializing it and passing it to the plugin configuration:

plugins.push(enableGoogleGtagAnalytics());

The complete clientContext.ts file is provided below:

'use client'; import { ClientContextComponent, createClientUniformContext, useInitUniformContext, } from '@uniformdev/canvas-next-rsc/component'; import { ContextPlugin } from '@uniformdev/context'; import { enableGoogleGtagAnalytics } from '@uniformdev/context-gtag'; export const UniformClientContext: ClientContextComponent = ({ manifest }) => { useInitUniformContext(() => { const plugins: ContextPlugin[] = []; plugins.push(enableGoogleGtagAnalytics()); return createClientUniformContext({ manifest, plugins, defaultConsent: true, }); }); return null; };

Connecting Uniform Insights

Uniform Insights empowers marketers and growth specialists to understand the performance of their personalization and A/B tests within the context of content and experience management. It helps identify new optimization opportunities and provides real-time insights into visitor behavior. Learn more about it here.

Add the following environment variables to your project:

# insert the endpoint URL you just copied into your clipboard from the settings page UNIFORM_INSIGHTS_ENDPOINT = 'your endpoint url' # insert the API key provided by your Uniform account manager UNIFORM_INSIGHTS_KEY = 'your api key'

Import enableUniformInsights from the @uniformdev/context package and add it to the list of plugins (ensure that this is activated client-side):

'use client'; import { ClientContextComponent, createClientUniformContext, useInitUniformContext, } from '@uniformdev/canvas-next-rsc/component'; import { ContextPlugin, enableUniformInsights } from '@uniformdev/context'; export const UniformClientContext: ClientContextComponent = ({ manifest }) => { useInitUniformContext(() => { const plugins: ContextPlugin[] = []; plugins.push( enableUniformInsights({ endpoint: { type: 'proxy', path: '/api/analytics', }, }) ); return createClientUniformContext({ manifest, plugins, defaultConsent: true, }); }); return null; };

Add a proxy route (src/app/api/analytics/route.ts) to your Next.js application to rewrite the path 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 }); }

Conclusion

Plugins significantly enhance functionality, simplify debugging and personalization optimization, enable the integration of personalization and testing data into Google Analytics, and provide real-time analytics. Additionally, you can combine these plugins and activate only those that meet your specific needs.

Below is an example of how to connect all the plugins discussed in this guide:

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