Implement Segment-Based Content Personalization in Your SPA (Engagement)

👍

For content personalization using segmentations managed in an external Customer Data Platform, see Implement Segment-Based Content Personalization in Your SPA (External CDP).

Introduction

Goal

Render pages in your SPA that use content personalization based on segmentations managed in Bloomreach Engagement.

Background

Bloomreach Content provides page-level content personalization based on segmentations managed in Bloomreach Engagement.

This page explains how to render such personalized pages in your SPA frontend.

Prerequisites

Segment-based content personalization in Bloomreach Content works together with the Bloomreach Engagement SDK. You need to have a Bloomreach Engagement account to make it work.

Additionally, you must add the Bloomreach Engagement Integration and Synchronize Segmentations from Engagement.

Before implementing personalization in your website you should already have the SPA SDK (v15.4.3 or greater) installed in your SPA.

Enable personalization in the Reference SPA

If you cloned the Reference SPA after March 28, 2023, segment-based personalization using Engagement is already included and you only need to configure your Engagement project token and API base URL.

In your .env file, you'll find the following parameters commented out:

# NEXT_PUBLIC_PERSONALIZATION_PROJECT_TOKEN=
# NEXT_PUBLIC_PERSONALIZATION_API_URL=

Uncomment them and add the appropriate values, for example:

NEXT_PUBLIC_PERSONALIZATION_PROJECT_TOKEN=1a23456b-1234-12ab-12a3-ab1c23d456ef
NEXT_PUBLIC_PERSONALIZATION_API_URL=https://cloud-api.exponea.com

If you cloned the Reference SPA before March 28, 2023, you can either merge the latest version into your copy or follow the manual steps in the next section.

Implement personalization in your SPA:

Add the Engagement SDK Snippet

First, get the Bloomreach Engagement SDK snippet. Log in to Bloomreach Engagement. In the top right corner click settings and choose Web Integration.

In the Event tracking window, click the Copy to clipboard button.

In your SPA, find the file in which the HTML <head> is rendered. The exact file depends on which implementation of the Reference SPA you used as a starting point. Paste the snippet you just copied inside the <head>. More details can be found in the Bloomreach Engagement Javascript SDK guide.

👍

Make sure you are using version 3.0.0 or later of the Engagement SDK snippet. To confirm the version of your snippet, search for a string "snippetVersion". The snippet should contain ["snippetVersion"]="v3.0.0".

Version 3.0.0 or later is required to support up to 30 exposed segmentations in Engagement (previous versions support only 5).

Use the Bloomreach Segmentation Library

Add the @bloomreach/segmentation library to your SPA to make the segmentation feature work. In the root folder of your SPA project, run the following command:

npm install @bloomreach/segmentation

In your SPA, import the segmentation library:

import { initializeSegmentation } from '@bloomreach/segmentation';

Call initializeSegmentation from the library.:

initializeSegmentation();

The initializeSegmentation function should be called on each render of the page.

That’s all!

The Bloomreach Engagement SDK sets a cookie called __exponea__etc__ with the ID of the user.

The segmentation library retrieves the segment IDs for the user, based on the project token and the user ID, and stores them as comma separated values in a cookie called __br__segment_ids.

The SPA SDK reads the value of the __br__segment_ids cookie and passes it in a __br__segmentIds query parameter to the Delivery API's Pages endpoint.

In the response from the API you get personalized content.

👍

Version 14 or later of the @bloomreach/segmentation library is required to support up to 30 exposed segmentations in Engagement (earlier versions only support 5).