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. });
curl -X 'GET' \ 'https://uniform.app/api/v2/manifest?preview=false&projectId=[!!! UNIFORM PROJECT ID !!!]' \ -H 'accept: application/json' \ -H 'x-api-key: [!!! UNIFORM API KEY !!!]'

With edge-side personalization, it is critical that the same manifest is available to the Uniform tracker that runs on the server and in the front-end application. The general process is:

  • Retrieve the manifest on the server.
  • 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.

  1. Add the following file:

    lib/context.js

    import { Context } from "@uniformdev/context"; import { NextCookieTransitionDataStore } from "@uniformdev/context-next"; import { NextPageContext } from "next"; export default function createUniformContext(manifest, serverContext) { return new Context({ defaultConsent: true, manifest, transitionStore: new NextCookieTransitionDataStore({ serverContext, }), }); }

    About this step

    This function creates the Uniform tracker. It is used to create both the server-side tracker and the client-side tracker. If you already have a function like this, change it so you can pass the manifest into it (instead of reading the manifest from a file).

  2. In your _document file, add the following code:

    import { ManifestClient } from "@uniformdev/context/api"; import createUniformContext from "../lib/context"; async function getManifest() { const manifestClient = new ManifestClient({ apiKey: process.env.UNIFORM_API_KEY, projectId: process.env.UNIFORM_PROJECT_ID, }); return manifestClient.get(); };

    About this step

    This function runs on the server. It reads the latest published manifest from your Uniform project. Since it runs on the server, it has access to environment variables.

  3. In the function getInitialProps, add the following code:

    static async getInitialProps(ctx) { const manifest = await getManifest(); const serverTracker = createUniformContext(manifest, ctx); enableNextSsr(ctx, serverTracker); const initialProps = await Document.getInitialProps(ctx); return {...initialProps, manifest}; }

    About this step

    This creates the Uniform tracker used during the server-side rendering. The tracker is configured to use the manifest retrieved from Uniform. Finally, the manifest is made available to the document as a prop.

  4. In the function render, add the following code in the tag Head:

    <script id="manifest" type="application/json" dangerouslySetInnerHTML={{__html: JSON.stringify(manifest)}} />

    About this step

    This injects the manifest into the page so it is available on the code that runs on the client.

  5. In your _app file, add the following code:

    import { UniformContext } from "@uniformdev/context-react"; import createUniformContext from "../lib/context"; // IMPORTANT: importing all components registered in Canvas import "../components/canvasComponents"; import "../styles/styles.css"; function MyApp({ Component, pageProps, serverUniformContext }) { let manifest = { project: {} }; if (typeof window !== "undefined") { const json = document.getElementById("manifest")?.innerHTML; if (json) { manifest = JSON.parse(json); } } const clientContext = createUniformContext(manifest); return ( <UniformContext context={serverUniformContext ?? clientContext} > <Component {...pageProps} /> </UniformContext> ); } export default MyApp;

    About this step

    This creates the client-side tracker using the manifest that was injected by the server-side code that you added in the previous step.

Coming soon

Last modified
Previous
Signals
Next
A/B testing