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.

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).

ScenarioOptionNotes
Optimize application performanceBuild-timeYour application application does not need to make an additional request to fetch the manifest.
Minimize runtime dependenciesBuild-timeEvery 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 expensiveRuntimeIf the application can retrieve the manifest itself, the manifest does not have to be bundled with the application.
Manifest changes frequentlyRuntimeIf the manifest changes often, it may be easier to have the application retrieve the manifest when it needs it.

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.

These steps will you to download the manifest to a file manifest.json from a terminal.

  1. If it's not already installed, install the CLI globally.

  2. If it's not already installed, install the package @uniformdev/context globally.

  3. 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.

A type ManfestClient is available in the npm package @uniformdev/context. The following code demonstrates how to use this type to retrieve the manifest.

import { ManifestClient } from '@uniformdev/context/api'; const manifestClient = new ManifestClient({ apiKey: "[!!! UNIFORM API KEY !!!]", projectId: "[!!! UNIFORM PROJECT ID !!!]", }); manifestClient.get().then(manifest => { // // Do something with the manifest. });

These steps will allow you to download the manifest to a file manifest.json using an npm script.

  1. If it's not already added to your application, install the CLI.

  2. If it's not already added to your application, install the package @uniformdev/context in the project.

  3. Add the following file:

    .env

    UNIFORM_PROJECT_ID=<UNIFORM PROJECT ID> UNIFORM_API_KEY=<UNIFORM API KEY>
  4. Add the following to the scripts section of package.json:

    "download:manifest": "uniform context manifest download -o ./manifest.json",
  5. 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:manifest

    What has changed

    When the command finishes, a file manifest.json is created.

The manifest can be downloaded using the REST API.

const axios = require("axios"); axios.get('https://uniform.app/api/v2/manifest', { params: { preview: false, projectId: "[!!! UNIFORM PROJECT ID !!!]", }, headers: { accept: "application/json", "x-api-key": "[!!! UNIFORM API KEY !!!]", } }).then(response => { const manifest = response.data; // // Do something with the manifest. });

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:

  1. Retrieve the manifest in the edge logic.
  2. Inject the manifest into the front-end application in a script tag.
  3. 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

  1. This example expects you already have the Uniform Edge Middleware handler incorporated into your application. For more information, see the Vercel integration documentation.
  2. 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.
  1. Add the following npm package to your application:

    npm i node-html-parser
  2. Add the following code to your middleware so you can use the HTML parser:

    import HTMLParser from "node-html-parser";
  3. 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).
  4. Change the code that creates the Context object to use the getManifest function:

    const context = new Context({ defaultConsent: true, manifest: await getManifest(), transitionStore: new CookieTransitionDataStore({ serverCookieValue, }), });
  5. Find the code that returns the response. This is probably something like the following, located near the bottom of the file:

    return response;
  6. 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, })
  7. 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.

  8. 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: [], });
  9. Deploy your changes to Vercel. Reload your application.