Request a demo
Home/Recipes/Personalizing list content
Personalizing list content
This recipe describes how to enable content authors to configure personalized lists that are based on a combination of what they know about their site's visitors and content.

About this recipe

This recipe describes how to enable content authors to configure personalized lists that are based on a combination of what they know about their site's visitors and content.

Use case

  • A content author can define personalization rules that determine which entries in a reference list are displayed and the order the entries are displayed.
  • An entry may be used in multiple reference lists, but the personalization rules are applied to the list of entries, rather than the entries themselves.

Real-world scenario

  • Content authors manage website content and personalization in Contentful.
  • Uniform enables content authors to configure personalization in Contentful.
  • The website is built using Next.js.
Location detail pages play a large role on your website. Rather than being limited to a specific section of the site, locations are available throughout. Your content authors create curated lists of locations in Contentful.
They want to add personalization to these curated lists. However, the personalization rules that apply to a location depend on the list, not the location.
The headquarters location may always be displayed on a list of locations in the "about us" section of the site, but when that same location is included in a location list in the "training" section, it only need to be displayed if the visitor is located in the same country as the headquarters.

Prerequisites

This recipe assumes you have the following:
  • Your Contentful space has the Uniform app installed.
  • Your Next.js application already has personalization activated.
  • Your Next.js application uses the page router and TypeScript.Technically neither of these is a requirement for the approach described in this recipe, but the instructions are written for an app that uses this configuration.
  • Your Next.js application uses client-side personalization.This recipe will work with edge-side personalization, but in order to keep the instructions as simple as possible, these instructions assume client-side personalization is used.

Headless CMS setup

Create content type: Personalization Rule

A personalization rule is an instruction that controls how personalization operates. Just like rules in the real world, a personalization rule describes two things:
What does this describe?How this will be implemented in this solution?CriteriaWhat needs to be true in order for the rule to take effect.This solution involves two criteria: visitor classification and enrichment tags assigned to the location in the list. For example, the personalization rule will take effect if the visitor is interested in a certain topic and the location is tagged with that same topic.ActionWhat happens when the condition is true.This solution supports two actions for when the criteria is true: the location will be boosted to the top of the list, or the location will be removed from the list.
The following steps describe how to create a content type that allows a content author to describe personalization rules.
  1. In Contentful, create the following content type:NamePersonalization RuleApi IdentifierpersonalizationRule
  2. Add the following field:PropertyValueNotesField typeShort textNameNameField IDnameThis field represents the Entry titleCheckedRequired fieldCheckedABOUT THIS STEPThis is a human-readable description of the personalization.
  3. Add the following field:PropertyValueNotesField typeShort textNameActionField IDActionRequired fieldCheckedAccept only specified valuesCheckedboost and hideAppearanceDropdownABOUT THIS STEPThis field allows the content author to control the action for the personalization rule. This action is applied to the locations in the list when the criteria (not yet configured) is met.
  4. Save the content type.
  5. Open the Uniform app configuration page.ABOUT THIS STEPYou get to the Uniform by by navigating to Apps > Installed apps > Uniform > Configure.
  6. Enable enrichment taggings on the content type.
  7. Enable personalization criteria on the content type.Be sure to click the Save button
  8. Return to the content type.
  9. Rename the following fields:Current nameNew nameNotesEnrichment TagsContent CriteriaThis field represents part of the personalization rule's criteria. It allows content authors to specify the enrichment tags that must be assigned to the location in order for the personalization rule to take effect.Personalization CriteriaVisitor CriteriaThis field represents part of the personalization rule's criteria. It allows content authors to specify the classification dimensions must be true of the visitor's session in order for the personalization rule to take effect.
  10. Add the following field:PropertyValueNotesField typeShort textNameContent Criteria Match TypeField IDcontentCriteriaMatchTypeAccept only specified valuesCheckedall and anyAppearanceRadioABOUT THIS STEPThis field represents part of the personalization rule's criteria. The field Content Criteria allows the content author to select multiple enrichment tags. This field allows the content author to specify specify how many of the selected enrichment tags must be set on the content in order for the rule to take effect: all means every one of the selected tags must be set, while any means just one of the selected tags must be set (any).
  11. Change the order of the fields to the following:PositionField name1Name2Action3Visitor Criteria4Content Criteria5Content Criteria Match Type
  12. Save the content type.

Update content type: Location

In this example, a content type already exists that represents a location. Enrichment tagging has already been enabled on the content type, so no changes are needed.

Update content type: Curated Location List

In this example, a content type already exists that represents a location list. You need to add the ability for content authors to assign personalization rules so they can control personalization.
  1. Open the content type Curated Location List.
  2. Add the following field:PropertyValueNotesField typeReferenceNamePersonalization RulesField IDpersonalizationRulesTypeMany referencesRequired fieldCheckedAccept only specified entry typeCheckedPersonalization RuleAppearanceDropdownABOUT THIS STEPThis field allows the content author select the personalization rules that apply to the entries in the field Locations.
  3. Change the order of the fields to the following:PositionField name1Title2Personalization Rules3Locations
  4. Save the content type.

Update Next.js application

You have given content authors the ability to configure personalization. Now you need to update the Next.js application in order to make that configuration available to the code responsible for displaying location lists.
  1. Add the following npm packages:
    1npm i @uniformdev-collab/rule-based-personalization
2npm i @uniformdev-collab/rule-based-personalization-contentful
3npm i @uniformdev-collab/rule-based-personalization-react npm i @uniformdev-collab/rule-based-personalization-react-contentful
  2. In your _app.tsx file, add the following before the default component is defined:
    1import {
2  ContentfulPzConfigLookupConfig,
3  ContentfulPzRuleLookupConfig,
4} from "@uniformdev-collab/rule-based-personalization-contentful";
5
6/**
7 * Define how Uniform should handle the personalization 
8 * entries that have personalized lists on them.
9 */
10const contentfulPzConfigs: ContentfulPzConfigLookupConfig = {
11  /**
12   * There is no default configuration, which means that 
13   * a content type must be specifically configured in 
14   * the 'elements' section in order for Uniform to be
15   * able to personalize a list on an entry.
16   */
17  defaultElement: undefined,
18  elements: {
19    /**
20     * The settings below only apply to entries with 
21     * the content type 'curatedLocationList'.
22     */
23    curatedLocationList: {
24      contentEntriesFieldId: "locations",
25      pzRulesFieldId: "personalizationRules",
26    },
27  },
28};
29
30/**
31 * Define how Uniform should handle the entries that represent
32 * the personalization rules that control personalized lists.
33 */
34const contentfulPzRuleConfigs: ContentfulPzRuleLookupConfig = {
35  /**
36   * These settings are used for entries that represent 
37   * personalization rules. These are the default settings.
38   * The 'elements' section can be used to define settings 
39   * that apply to specific content types.
40   */
41  defaultElement: {
42    /**
43     * Entry field that represents the rule name.
44     */
45    nameFieldId: "name",
46    /**
47     * Entry field that represents the rule action.
48     */
49    actionFieldId: "action",
50    /**
51     * Entry field that represent the content criteria
52     * match type (i.e. 'all' or 'any').
53     */
54    contentCriteriaMatchTypeFieldId: "contentCriteriaMatchType",
55  },
56  /**
57   * There are settings that only apply to a specific content type.
58   */
59  elements: {},
60};
  3. Add the following code: ./src/pages/_app.tsx
    1import { 
2  RuleBasedPersonalization, 
3} from "@uniformdev-collab/rule-based-personalization-react";
4
5...
6
7  <UniformContext context={...}>
8    <RuleBasedPersonalization 
9      context={clientContext} 
10      pzConfigs={contentfulPzConfigs} 
11      pzRuleConfigs={contentfulPzRuleConfigs}
12    >
13      ...
14    </RuleBasedPersonalization>
15  </UniformContext>
16...
    CopyCopied!
  4. In the page that has the component that displays the location list, add the following code:
    1import { Entry } from "contentful";
2import { useEffect, useState } from "react";
3import { 
4  useUniformContext,
5} from "@uniformdev/context-react";
6import { 
7  useContentfulRuleBasedPz,
8} from "@uniformdev-collab/rule-based-personalization-react-contentful";
9
10...
11
12export default function HomePage(props: HomePageProps) {
13  const { context } = useUniformContext();
14  const { doPersonalize } = useContentfulRuleBasedPz();
15  const [locations, setLocations] = useState<Entry>();
16  /**
17   * This example assumes the Contentful entry is provided
18   * in props. This entry should represent the curated 
19   * location list.
20   */
21  const { entry } = props;
22
23  /**
24   * On mount, run personalization and add event listeners 
25   * on the tracker so personalization runs when visitor
26   * dimensions change.
27   */
28  useEffect(() => {
29    personalize();
30    context.events.on("scoresUpdated", personalize);
31    return () => {
32      context.events.off("scoresUpdated", personalize);
33    };
34  }, []);
35
36  function personalize() {
37    if (entry) {
38      const { personalized } = doPersonalize(entry);
39      
40      /**
41       * This example assumes 
42       */
43      setLocations(personalized);
44    }
45  }
46
47...

Use the solution

The video at the top of this page demonstrates how the solution is used.
  1. Create a new entry using the content type Curated Location List.
  2. Create new entries using the content type Personalization Rule.
  3. Assign the personalization rules to the field Personalization Rules.
  4. Publish the entries.
  5. Test the personalization.

Experience what you can deliver with Uniform today

Schedule Demo