Conditional Uniform Context dev tools
TroubleshootingDeveloperRecipePersonalization
Uniform Context dev tools are a helpful tool for testing and debugging personalization. When Context dev tools are activated and the visitor has our browser extension installed, the visitor is able to simulate visitor activity.
This recipe describes how to disable Context dev tools by default, but to enable it to be activated using a hidden page in your front-end application.
You can create a debug page that lets you activate and deactivate Uniform Context dev tools.
About this recipe#
Use case#
- By default, visitors to the production website cannot access Uniform Context dev tools.
- Your internal teams may need to access Uniform Context dev tools on the production website, but you don't want to have to make any code changes to enable this.
Real-world scenario#
You have just launched a new personalization campaign on your website. You are getting ready to promote it, but you need to make sure it is working as expected in production. The Uniform Context browser extension lets you do this, but the following workflow is not ideal:
- Ask developers to enable Context dev tools in production.
- Do your testing.
- Ask developers to disable Context dev tools.
Instead, you want your testers to be able to enable Context dev tools when they need to, without needing to involve the development team or requiring any code changes.
Setup#
Prerequisites#
This recipe assumes you have the following:
- Your Next.js application already has Uniform Context dev tools enabled.
- Your Next.js application uses the page router and TypeScript.
Technically neither of these is a requirement for the approach described in this recipe, but the instructions are written for an app that uses this configuration.
- Your Next.js application uses Tailwind CSS.
This is only required in order to make the hidden page match the formatting on the rest of the site.
- You have the Uniform Context browser extension installed.
Update the context plugin config#
- Add the following npm package:
npm i js-cookie
npm i -D @types/js-cookie
- Find the code that configures the context plugins. It will look something like the following:
const clientContext = new Context({
defaultConsent: true,
manifest: manifest as ManifestV2,
transitionStore: new NextCookieTransitionDataStore({
serverContext: undefined,
}),
plugins: [
enableContextDevTools(),
],
});
This code is probably in your _app.tsx file.
- Refactor this code so the Context dev tools plugin is only added if a specific cookie is set:
import Cookies from "js-cookie";
const plugins: ContextPlugin[] = [];
if (Cookies.get("_uniform-debug") === "true") {
plugins.push(enableContextDevTools());
}
const clientContext = new Context({
defaultConsent: true,
manifest: manifest as ManifestV2,
transitionStore: new NextCookieTransitionDataStore({
serverContext: undefined,
}),
plugins,
});
Create the hidden control page#
- Add the following page to your front-end app:
pages/debug.tsx
import Cookies from "js-cookie";
import { useEffect, useState } from "react";
export default function DebugPage() {
/**
* State variable to store the value that indicates
* whether debug mode is active or not.
*/
const [debugMode, setDebugMode] = useState<string>();
/**
* Set the debug mode state variable based on the
* cookie value.
*/
useEffect(() => {
const value = Cookies.get("_uniform-debug");
setDebugMode(value === "true" ? "ON" : "OFF");
}, []);
/**
* Event handler for when the user wants to activate
* or deactivate debug mode.
*/
function toggleDebugMode() {
let action = "";
if (debugMode === "ON") {
Cookies.remove("_uniform-debug");
action = "deactivated";
} else {
Cookies.set("_uniform-debug", "true");
action = "activated";
}
const result = confirm(
`Debug mode will not be ${action} until the application reloads. Do you want to reload the application?`
);
if (result) {
document.location.reload();
}
}
if (!debugMode) return;
const action =
debugMode === "ON" ? (
<span className="font-bold text-red-800">DISABLE</span>
) : (
<span className="font-bold text-green-800">ENABLE</span>
);
return (
<>
<h1>Debug mode: {debugMode}</h1>
<div>
<p>
When debug mode is on, the Uniform Context dev tools plugin is enabled
in the application. This means visitors who have the Uniform browser
extension installed may be able to control classification and
personalization on your site.
</p>
<p>
To {action} debug mode, <a onClick={toggleDebugMode} href="#">click here</a>.
</p>
</div>
</>
);
}
Use the solution#
- In your browser, open your website. The browser extension will be disabled.
- Navigate to
/debug. - Enable debug mode. The browser extension will be enabled.
Last modified: January 6, 2025