Manifest
In order for the Uniform tracker to classify a visitor, it needs to know what to track. The Uniform manifest provides this information.
The Uniform manifest is a JSON object that describes the classification criteria that are configured in Uniform. The settings included in the manifest are defined in a Uniform project under the sections Personalization and Testing. The Uniform tracker uses the manifest in order to know how to classify visitors.
When to retrieve the manifest#
A basic decision you must make is whether to incorporate the manifest into your application (build-time), or for your application to include logic to retrieve the manifest itself (runtime).
Scenario | Option | Notes |
---|---|---|
Optimize application performance | Build-time | Your application application does not need to make an additional request to fetch the manifest. |
Minimize runtime dependencies | Build-time | Every additional API your application requires at runtime creates another dependency for your application. Bundling the manifest at build-time eliminates the dependency on the availability of the Uniform Manifest API at runtime. |
Application rebuilds are expensive | Runtime | If the application can retrieve the manifest itself, the manifest does not have to be bundled with the application. |
Manifest changes frequently | Runtime | If the manifest changes often, it may be easier to have the application retrieve the manifest when it needs it. |
How to retrieve the manifest#
In order for classification and personalization to work, your application needs to have access to the manifest.
Uniform API key is required
All of these approaches require an API key with the following permissions:
- Uniform Context > Manifest > Read
If you need an API key, you can create one in the Uniform dashboard.
CLI#
These steps will you to download the manifest to a file manifest.json
from a terminal.
If it's not already installed, install the CLI globally.
If it's not already installed, install the package
@uniformdev/context
globally.Run the following command:
uniform context manifest download \\ -o ./manifest.json \\ -p <UNIFORM_PROJECT_ID> \\ -k <UNIFORM API KEY>What has changed
When the command finishes, a file
manifest.json
is created.
Npm package#
A type ManfestClient
is available in the npm package @uniformdev/context
. The following code demonstrates how to use this type to retrieve the manifest.
Npm script#
These steps will allow you to download the manifest to a file manifest.json
using an npm script.
If it's not already added to your application, install the CLI.
If it's not already added to your application, install the package
@uniformdev/context
in the project.Add the following file:
.env
UNIFORM_PROJECT_ID=<UNIFORM PROJECT ID> UNIFORM_API_KEY=<UNIFORM API KEY>Add the following to the
scripts
section ofpackage.json
:"download:manifest": "uniform context manifest download -o ./manifest.json",You can run the command from a terminal, or as a part of another npm script using the following command:
Download manifest
npm run download:manifestWhat has changed
When the command finishes, a file
manifest.json
is created.
REST API#
The manifest can be downloaded using the REST API.
Examples#
Runtime retrieval with SSG & edge-side personalization#
With edge-side personalization, it is critical that the same manifest is available on the edge and the front-end application. The general process is:
- Retrieve the manifest in the edge logic.
- Inject the manifest into the front-end application in a script tag.
- Configure the front-end application to load the manifest from the script tag.
This example demonstrates how to modify a Next.js application deployed to Vercel to retrieve the Uniform manifest at runtime.
About this example
- This example expects you already have the Uniform Edge Middleware handler incorporated into your application. For more information, see the Vercel integration documentation.
- This example is for a Next.js page router application. If you are using a different type of application, you will need to make changes.
Add the following npm package to your application:
npm i node-html-parserAdd the following code to your middleware so you can use the HTML parser:
import HTMLParser from "node-html-parser";Add the following code to retrieve the manifest at runtime:
import { ManifestClient } from '@uniformdev/context/api'; async function getManifest() { const manifestClient = new ManifestClient({ apiKey: process.env.UNIFORM_API_KEY, projectId: process.env.UNIFORM_PROJECT_ID, }); return manifestClient.get(); };Performance implications
This code will add approximately 100ms to the time it takes to run the middleware. You may want to retrieve the manifest from Vercel Edge Config in order to optimize performance. Vercel claims reads will complete in 15ms or less.
The following describes how you can implement this approach:
- Uniform supports a webhook that can be triggered when the manifest is published.
- Configure this webhook to call a custom endpoint (i.e. you must build this) that retrieves the published manifest from Uniform and writes it to Vercel Edge Config.
- Modify the code above to retrieve the manifest from Vercel Edge Config (instead of from Uniform directly).
Change the code that creates the
Context
object to use thegetManifest
function:const context = new Context({ defaultConsent: true, manifest: await getManifest(), transitionStore: new CookieTransitionDataStore({ serverCookieValue, }), });Find the code that returns the response. This is probably something like the following, located near the bottom of the file:
return response;Replace the code that returns the response with the following to inject the manifest into the response:
const doc = HTMLParser.parse(await response.text()); const headTags = doc.getElementsByTagName("head"); if (headTags.length === 1) { const json = JSON.stringify(context.manifest.data); const tag = `<script id=\"manifest\" type=\"application/json\">${json}</script>`; const script = HTMLParser.parse(tag); headTags[0].appendChild(script); } return new Response(doc.innerHTML, { headers: response.headers, status: response.status, statusText: response.statusText, })In your application (not the middleware), find the code that reads the manifest and uses it to create a
Context
object. This code will look something like the following:import manifest from "./context-manifest.json"; const clientContext = new Context({ manifest, transitionStore: new NextCookieTransitionDataStore({ serverContext: undefined, }), plugins: [], });This code is similar to code in the middleware file, but if you look closely you will see differences. Be sure you are not looking at the middleware file.
Change this code so the manifest is read from the script tag that the middleware injected:
let manifest = { project: {} }; // // Only run this code on the client (i.e. not during SSG). if (typeof window !== "undefined") { // // Find the script tag injected by the middleware. const json = document.getElementById("manifest")?.innerHTML; if (json) { // // Parse the manifest from the script tag so it can be used. manifest = JSON.parse(json); } } const clientContext = new Context({ manifest, transitionStore: new NextCookieTransitionDataStore({ serverContext: undefined, }), plugins: [], });Deploy your changes to Vercel. Reload your application.