Skip to main content

Migrating to Uniform Context

Uniform Context is an advanced personalization engine that enables much more powerful personalization than its predecessor, Uniform Optimize.

Why migrate?

In short, Uniform Context is more powerful in every way than Uniform Optimize.

  • Powerful classification with better behavior tracking, aggregated values, and support for multiple criteria to trigger signals.
  • Control over selection of personalized variations. Instead of automatic complex math, you control the priority and selection criteria for each variation.
  • Excellent integration with external data such as CDPs to make personalization decisions.

If you are using Uniform Canvas, be aware that the Canvas packages at v15 and later are only compatible with Uniform Context. To continue using Uniform Optimize, ensure that you do not upgrade Canvas to v15 or later.

Understanding Uniform Context

We strongly recommend reading the introduction to Uniform Context before you start migrating so you understand how Context works and what its main concepts mean. You can also start an instance of Uniform Context on StackBlitz to experiment with it.

To migrate an Optimize project to Context there are four main points to be aware of:

  1. An Intent in Optimize is equivalent to a Signal in Context.
  2. A Signal in Optimize is equivalent to a Signal Criteria in Context. An Optimize Intent with more than one Optimize Signal is equivalent to a Context Signal with multiple criteria in a logical-OR group.
  3. Personalized variations in Optimize are selected based on a relevancy computation to the visitor's Optimize Intent scores. This can be difficult to predict, so Context simplifies variation matching by assigning an explicit criteria to each variation such as score in developer > 50. Variations are selected by evaluating each variation and picking the first one(s) that match, which means that unlike Optimize the order of variations matters. This also means that default variations should always be last in the list in Context.
  4. Uniform Optimize has a single intent tag content field that is used both for behavior tagging as well as assigning personalized variations either in Uniform Canvas or a headless CMS that has Uniform integrated. In Context this field is split into new enrichment tag (for behavior tagging) and personalization criteria (to control how a personalized variation is selected) fields for their different purposes. When migrating the existing intent tag data is left alone and the new enrichment tag and personalization criteria fields are added as new data to the content model.

How the migration process works

Uniform Context uses a different classification model than Uniform Optimize. To make migrating easier without breaking any existing implementation code, Context stores its data separately from Optimize. When you start migrating to Context all your Optimize configuration, data, and content remains intact and is not changed by any actions you take in Context.


Enrichments are the one exception to this rule: they work identically between Optimize and Context and share the same data between both. No migration is needed for Enrichments.

Getting started

Switch to Context mode

The first step in the migration process is to switch your Uniform project to Context mode. This is done with a switch on the project's General Settings page.


You can still change and publish Optimize configuration during the migration process by temporarily turning off Context to access the Optimize interfaces. Doing this will not remove any Context data or interrupt your migration process.

Define Context classification model

As outlined above:

  1. Optimize Intents become Context Signals
  2. Optimize Signals become Context Signal Criteria

Don't forget to publish your Context classification model by clicking the Publish button. This will publish a Context manifest for your website to use (does not affect the Optimize manifest).

If you are tagging content in a Headless CMS

Uniform Optimize has integrations with several popular headless CMS that allow you to add behvaior and personalization tags to content objects in the CMS. If you are using one of these integrations, you will need to add new metadata to your content models to support Uniform Context. Uniform Optimize integrations offer one type of custom content field: the intent tag, which can be used either for adding score due to visitor behavior or to customize when a personalized variation is shown. Uniform Context splits this field into two new fields: the enrichment tag and personalization criteria.

To upgrade to Context within your CMS app:

  1. The act of switching the connected Uniform project to Context mode will activate the Context UIs in the CMS integration automatically.
  2. Fields added to your content model for Intent Tags should be left alone, and will continue to carry the intent tag data while migration is in progress.
  3. Add a new field for enrichment tags to any content types that you wish to be able to add behavior tracking to (adding score to an enrichment when the content is viewed by a visitor).
  4. Add a new field for personalization criteria to any content types that you wish to be able to act as a personalized variation in a Context personalization.
  5. Fill out the new Context fields with appropriate enrichment tags or personalization criteria.
  6. For any Personalization list content types that are related to personalized variation types, remember that the order specified in that relation now matters in terms of selection. Make sure default variations go last and the most important variations are first.

Don't forget to publish any content you wish to consume into Context after adding the new Context data to it.

If you are using Uniform Canvas

Because Context and Optimize store their data in separate parellel component parameters to facilitate easy upgrades, Canvas Compositions with Optimize tag data will need to have Context tag data added once they are switched into Context mode.

Review each of your compositions with personalization data or behavior tags and update them to Context's enrichment tags and personalization criteria.


Keep in mind that personalization order matters in Context, so make sure default variations go last and the most important variations are first. Re-ordering variations will not have any effect on how the content renders in Optimize.

Don't forget to publish your compositions so the Context data is available on them.

Upgrade your web app to use Context packages

In order for your web app to use Context, you need to switch from @uniformdev/optimize-* npm packages to @uniformdev/context-* packages.

  1. In your web app's package.json, delete all @uniformdev/optimize* packages.

  2. Install Context packages. For example in a Next.js application: npm i @uniformdev/context @uniformdev/context-react @uniformdev/context-next.

  3. If you are using Uniform Canvas, ensure that all Canvas packages are on the latest version (v15 or later).

  4. Reconfigure your npm script that downloads your Uniform Manifest to download a Context manifest instead, by changing uniform optimize manifest download to uniform context manifest get.

  5. Reconfigure your Uniform tracker initialization to use Uniform Context instead:

    import { Context, ManifestV2, enableContextDevTools } from '@uniformdev/context';
    import { NextCookieTransitionDataStore } from '@uniformdev/context-next';
    import { NextPageContext } from 'next';
    import manifest from './manifest.json';

    export function createUniformContext(serverContext?: NextPageContext) {
    const context = new Context({
    manifest: manifest as ManifestV2,
    // enable storage consent by default (optional)
    defaultConsent: true,
    // configure next.js for SSR (if not using SSR, you can omit the transitionStore)
    transitionStore: new NextCookieTransitionDataStore({
    // enable the Uniform Context Chrome Extension to connect (optional)
    plugins: [enableContextDevTools()],

    return context;

Deploy Uniform Context

Once you deploy your web app with the Uniform Context migration completed, you're all done.