Personalization

Personalization is the practice of tailoring digital experiences to meet the specific needs and preferences of individual visitors. By delivering customized content, you can create more relevant and engaging experiences that drive better conversion rates and customer satisfaction.

With Uniform, you can personalize experiences based on various dimensions:

  • Behavior - Adapt to past and current visitor activity
  • Preferences - Respond to explicitly shared information
  • Inferred interests - Personalize based on observed patterns
  • Location - Customize based on geographic location

Uniform's personalization framework lets you define visitor dimensions, create conditions based on these dimensions, and connect them to components in your application. The platform also provides sophisticated logic to evaluate these conditions and determine the best content to display for each visitor.

tip

Personalization relies on effectively classifying your audience using Uniform's classification tools.

To personalize an experience you select different variations of components to show to different visitors in a specific Personalization component. Each variation can have criteria that allow it to be evaluated against the visitor's classification to determine if it's shown. A variation that has no criteria is the default variation that's shown to anyone if no more specific variation is matched.

Uniform can apply different selection methods for how variations are matched.

  • Strongest variation matching - This selection method personalizes content for a specific dimension. Visitors are shown the variation matching their strongest dimension among variations.
  • Top-down criteria matching - Uniform starts at the beginning of the Personalization component's variation list. Each variation's criteria is evaluated, and the first matching variation is selected.
  • Custom matching methods - Register and implement your own custom selection methods via Uniform's Mesh framework when you need bespoke personalization logic.

The strongest variation matching selection method evaluates all variations within a Personalization component and selects the one that best matches the current visitor's profile.

This selection method is ideal for straightforward personalization scenarios that don't involve complex criteria rules or multiple dimensions. It performs effectively when personalizing based on enrichment categories or when working with multiple dimensions that share comparable scoring scales.

Key characteristics of strongest variation matching:

  • Each variation is associated with a single dimension (like an audience or interest) rather than complex criteria sets
  • Only variations explicitly defined within the Personalization component are evaluated - even if a visitor has high scores in other dimensions, those won't be considered unless they're included in a variation
  • The order of variations is only important when there's a tie in scores (for example, if a visitor scores equally in two different dimensions) - in this case, the first matching variation in the list is selected

note

Please refer to the compatibility section for more information on SDK version requirements and feature availability.

The following example shows a Personalization component with these variations using the "Strongest variation matching" selection method:

  • Variation 1: 'Consumer' audience is selected
  • Variation 2: 'Marketers' audience is selected
  • Variation 3: No dimension is selected - this is the default variation

In this scenario, a visitor who had:

  • No scores at all: Variation 3 is shown because no variations match the visitor's profile, so the default variation is selected
  • A score in the 'Consumer' audience of 50: Variation 1 is shown because it has the strongest match for the visitor's profile
  • A score in the 'Marketers' audience of 75: Variation 2 is shown because it has the strongest match for the visitor's profile
  • A score in both 'Consumer' audience of 30 and 'Marketers' audience of 60: Variation 2 is shown because the 'Marketers' score of 60 is stronger than the 'Consumer' score of 30
  • A score in both 'Consumer' audience of 80 and 'Marketers' audience of 40: Variation 1 is shown because the 'Consumer' score of 80 is stronger than the 'Marketers' score of 40
  • Equal scores in both audiences (e.g., 50 in 'Consumer' and 50 in 'Marketers'): Variation 1 is shown because it's the first variation in the list with a matching score
  • A score in the 'Developers' audience of 100: Variation 3 is shown because there is no variation targeting the 'Developers' audience, so the default is selected

The top-down criteria matching selection method excels in complex personalization scenarios where:

  • You need to evaluate multiple dimensions simultaneously
  • You require specific criteria rules with precise logic
  • The order of evaluation is important to your personalization strategy

This approach is particularly effective when working with boolean or event-based dimensions like signals or quirks, where the sequence of rule evaluation directly impacts the personalization outcome.

To select a personalized variation, Uniform starts at the beginning of the Personalization component's variation list. Each variation's criteria is evaluated, and the first matching variation is selected. It's important to order your variations so that the most specific variations are first, and the least specific (default) variations are last.

Compared to the "Strongest variation matching" selection method, the "Top-down criteria matching" selection method has the following additional capabilities:

  • you can define more complex criteria rules for each variation:
    • criteria can use comparison operators to evaluate a score: equals, not equals, greater than, less than, greater than or equal to, less than or equal to, weakest score, strongest score across all categories, strongest category score
    • criteria can combine multiple criteria rules using logical operators: AND, OR
  • define the order of the variations to control which variations are evaluated first - this is important for criteria that dimensions that are more boolean in nature such as Signal or Quirk and where you need to control the sequence of evaluation.
  • Quirks can be used as criteria in a variation

The following example the following Personalization component is personalized using the "Top-down criteria matching" selection method:

  • Variation 1: Visitor score in the 'Consumer' audience is greater than 0
  • Variation 2: Visitor score in the 'Marketers' audience is less than 50
  • Variation 3: No criteria

In this scenario, a visitor who had:

  • No scores at all: Variation 3 is shown because none of the earlier variations match the visitor, and Variation 3 is a default variation
  • A score in the 'Consumer' audience of 50: Variation 1 because its criteria matched
  • A score in the 'Marketers' audience of 25: Variation 2 because its criteria of less than 50 matched
  • A score in the 'Marketers' audience of 51: Variation 3 because the marketer score is greater than variation 2's requirement
  • A score in both 'Consumer' and 'Marketers' audiences of 25: Variation 1 because it matched before Variation 2 (unless we were taking two or more variations for this Personalization component)
  • A score in the 'Developers' audience of 5000: Variation 3 because there is no matching variation for this audience so the default is selected

Allows you to implement alternative variation selection methods using the custom Mesh integrations.

This is ideal when:

  • You need specialized personalization expressions beyond the built-in methods
  • You want to personalize using external data sources or custom criteria

To implement a custom selection method:

  1. Create a custom Mesh integration that registers your custom selection method and provide the configuration UI for the variations

mesh-manifest.json

{ ...other Mesh manifest properties "locations": { ... other Mesh locations "personalization": { "selectionAlgorithms": { "dayOfWeek": { "displayName": "Day of week personalization", "description": "Example integration-provided personalization selection method UI for personalizing based on the day of the week", "criteriaEditorUrl": "/<path-to-your-custom-criteria-editor>" } } } ... other Mesh locations } ... other Mesh manifest properties }
  1. In your frontend application create a Context Plugin that defines the logic for the custom selection method

/lib/dayOfWeekPersonalization.ts

import { ContextPlugin, PersonalizationSelectionAlgorithm } from '@uniformdev/context'; import type { MyAlgorithmVariantMatchCriteria } from '../pages/reference/personalizationSelectionAlgorithm'; /** * Example personalization algorithm that selects a variation based on the day of the week * Must be registered as a plugin with the Context SDK instance that runs on your server/edge/client. * In order to have UI to assign the day of the week, you must also install an integration which provides the criteria editor UI. */ const dayOfWeekPersonalizationAlgorithm: PersonalizationSelectionAlgorithm< MyAlgorithmVariantMatchCriteria > = (options) => { const { variations, take } = options; const currentDate = new Date(); const currentDay = currentDate.getDay(); // 0-6, Sunday-Saturday const matchingVariations = Array.from(variations) .filter((variant) => variant.pz?.dayOfWeek === currentDay) .map((variant) => ({ ...variant, control: false, })) .slice(0, take); return { personalized: matchingVariations.length > 0, variations: matchingVariations, }; }; export const dayOfWeekPersonalizationPlugin: ContextPlugin = { personalizationSelectionAlgorithms: { // IMPORTANT: this must match the key used in your mesh manifest for the personalization algorithm 'dayOfWeek': dayOfWeekPersonalizationAlgorithm, }, };
  1. Register the custom Context Plugin to the Context tracker

/lib/context.js

import { registerDayOfWeekPersonalization } from './dayOfWeekPersonalization'; export function createUniformContext(serverContext?: NextPageContext) { // add your custom personalization plugin to the list const plugins: ContextPlugin[] = [dayOfWeekPersonalizationPlugin]; return new Context({ manifest: manifest as ManifestV2, plugins, }); }
  1. Select your custom algorithm in the "Selection method" dropdown when creating a Personalization component
  2. Configure variations with the data your custom algorithm expects

note

Custom selection methods must be registered in all relevant Context instances (edge, server, client) where personalization occurs.

Please refer to the compatibility section for more information on SDK version requirements and feature availability.

SDK requirements

To activate the Strongest variation matching and Custom matching selection methods in your frontend application the @uniformdev/context package in version v20.9.0 or higher is required.

The Strongest variation matching and Custom matching selection methods are only available for personalization within the Uniform visual editor.

These selection methods are not available for the Uniform apps for other headless CMSs like Contentful, Contentstack, Sanity or Kontent.ai which only support the Top-down criteria matching selection method.

You can nest personalization components within each other to create more complex decision trees. This approach is useful when you need multi-level targeting based on hierarchical data such as:

  • Parent and child categories or taxonomies
  • Regions → Cities

Nested personalization follows a simple outside-in evaluation process:

  1. The outer Personalization component evaluates first and selects its matching variation
  2. If the matching variation is another Personalization component, that inner component evaluates next
  3. This process continues through all nested levels

If no variations match at any level, the default variation for that Personalization component is shown.

Each Personalization component can be nested to any depth and each can have a different selection method.

Tracking for nested personalization

Analytics events are tracked for each level of the nested personalization.

nested-personalization
Example of a nested personalization component

In the screenshot above:

  • The outer component personalizes content based on travel regions
  • For the "Asia" region variation, we've added a nested component
  • This inner component further personalizes content based on travel budget

This two-level approach lets you show targeted content that meets multiple criteria simultaneously.

Any effective personalization strategy must be measured to make sure it's having a positive effect.

To enable this, Uniform enables you to connect its personalization results to any analytics tool available. Each Personalization component has an Analytics tracking name which is sent to any connected analytics along with the variation that was selected. The resulting data can then be analyzed and reported on in any way the analytics tool allows.

Uniform ships with a connector for Google Analytics 4 that enables Uniform to send tracking events to Google Analytics. Uniform also provides a generic event-handling interface that can be used to send tracking events to any other system with minimal custom development.

In addition to tracking the effect of personalized variations, it's important to track the effect of personalization vs no personalization to ensure your strategy is working. Uniform supports setting a control group which is a percentage of your users that's not exposed to any personalized variation regardless of their classification. Whether the visitor is part of the control group is sent to analytics for analysis. Control group members won't be shown personalization.

The default settings don't enable a control group to avoid confusion during evaluation and testing. For production a value of 15% is recommended.