Skip to main content

Personalizing with React

Optimize Deprecation

Uniform Optimize has been deprecated and replaced by Context, a more powerful and flexible personalization solution. Optimize is not being discontinued at this time, but it will not receive updates or new features.

We do not recommend starting a new project with Optimize. If you have an existing project that uses Optimize, you can upgrade your project to Context at no cost using our upgrade guide. If you have any issues with this process you can contact our team.

Most personalization forms involve selecting a single variation to display to a visitor from a list of possible variations. For example, we might have a promotional placement with a variation for high-value customers and a default variation for everyone else.

The Uniform <Personalize /> component can accept a list of possible variants and emit a rendered React component based on the type(s) of variants determined to be most relevant to the visitor.

Variation data

Variations are a JavaScript array of objects with content and personalization data. Variation data must be provided to the <Personalize /> component via the variations prop.

Variation data must implement the following interface:

// TypeScript
interface PersonalizableListItem {
// `intentTag` tells us which intents this variation is relevant to, which
// is used when evaluating whether or not a variation meets personalization criteria.
// Variations with no intent tag are considered 'default' and are shown to anyone.
intentTag?: IntentTags | null;
}
info

Variation data can be of any object type, but the intentTag property must be set on at least one variation for the personalization process to occur.

Generating variation data

While Uniform provides some helpers to simplify working with CMS data, you can choose to construct your variation data manually.

For example, if your Uniform-compatible CMS provides a list of post content items, you can Array.map() them to personalizable variations:

// replace `fetchPostsFromCMS` with something that fetches data from your CMS
const allPosts = await fetchPostsFromCMS();

const mappedPosts = allPosts.map((post) => {
return {
...post,
// Assumes your CMS is capable of attaching Uniform Intent tags
// to content items via `unfrmOptIntentTag` property.
intentTag: post.unfrmOptIntentTag,
};
});
note

Learn more about our CMS-specific helpers in the Content Management documentation.

Now that we have a list of posts in a personalizable format, we can pass these via the variations prop to the <Personalize /> component and let the component determine and render the closest matched variation for our site visitors.

<Personalize variations={mappedPosts} />

Controlling Rendering of Variations

<Personalize/> needs to know what React component to use to render a selected personalized variant. This is done by passing a React component directly into the <Personalize/> component's component prop:


tip

The props that your rendering component receives will be the object in the variations array at the selected index.

If your variations are [{ type: 'A'}, {type: 'B'}], and the selected variation to render is [1], then your React component will receive {type: 'B'} as props.

Handling More Than One Variation Type

If personalized variations can be of different types, you can use conditional logic to tell <Personalize /> which rendering component to use. Personalization might allow for Hero or CallToAction types, which would result in a different component being used to render them.

Here is an example of a component mapping:


Choosing Multiple Variations (Lists)

In many cases, personalization is choosing the single most relevant variation from a set of possible variations. But it is also possible to select more than one of the most-relevant variations; this enables scenarios such as:

  • Show the three most relevant promotions
  • Order a list of items by the most relevant to the visitor's intent scores

<Personalize /> can support this scenario by passing the count prop:


Custom Rendering

In some cases you may wish to wrap personalized variation(s) with some sort of wrapper when they exist; for example, to place a heading that changes whether something is personalized or not around a list of personalized results. For this, you can use the wrapperComponent prop.