Back to the blog
Published
  • Nov 2, 2021
  • --
Author
Category Business
Share
Headless Personalisation 1200x628
Introducing Headless Personalization

Introducing Headless Personalization

In a recent blog post in his “Headless Magnolia” series, my colleague Bartosz explained how to configure and fetch content from our Delivery API when using Magnolia as a headless CMS.

But while headless architectures are becoming more popular by the day, integrating personalization in a headless stack can be challenging. Considering the benefits of personalization, such as better customer experiences, greater visitor engagement, and higher conversion rates, we wanted to make headless personalization easier.

In this blog post, I am going to explain how we’ve enhanced our REST API to deliver content based on audience traits, enabling personalized experiences in headless projects with very little effort.

Enabling personalization in the Delivery API

To enable personalization for a delivery endpoint, add the personalized property to the endpoint’s YAML definition:

Java
  class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: website
personalized: true

Defining new traits

To request personalized content via the endpoint, we introduced 3 new trait types that developers can specify:

  • cookieTrait

  • requestParameterTrait

  • headerTrait

Each trait is defined in a YAML file in the traits folder of a Magnolia Light Module:

Java
  my-light-module/
└── traits
    └── my-trait.yaml

Once defined, a trait can immediately be used by content authors to create variants of personalized experiences in the Pages App and to preview experiences as a user with specific traits would see it.

Headless Magnolia: The Delivery Endpoint API

The Headless Magnolia series explains features that allow you to use Magnolia as a headless CMS. Read our blog post for an introduction to the Delivery endpoint API.

Requesting personalized content

I want to share an example from our demo project to show how to request content from a delivery endpoint based on two request parameters traits:

Java
  curl --location --request GET 'http://localhost:8080/magnoliaPublic/.rest/delivery/pages/v1/shoes?gender=men&favorite-color=white'

The endpoint’s response is personalized but node name and node path are masked to look like an original node:

Java
  "@name": "shoes",
 "@path": "/shoes",
 "@id": "ff1e3449-7c62-4952-baaf-5b798ca7f8d4",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "navigationTitle": "Shoes",
 "title": "Tommy Hilfiger | Shoes",
 "noCache": "false",
 "main": {
     "@name": "main",
     "@path": "/shoes/main",
     "@id": "963d48ec-f4cb-4b06-82a4-f80dd18dfbc4",
     "@nodeType": "mgnl:area",
     "0": {
         "@name": "0",
         "@path": "/shoes/main/0",
         "@id": "217032aa-6282-466e-a14f-44aeaf204058",
         "@nodeType": "mgnl:component",
         "@variantNodeName": "variant-0",
         "@variantPath": "/shoes/main/0/variants/variant-0"

If you look closely at the JSON response above, you’ll notice two new properties:

  • variantNodeName

  • variantPath

It is possible to specify multiple traits and trait types in the request, combining cookie, header, and request parameter traits:

Java
  curl --location --request GET 'http://localhost:8080/magnoliaPublic/.rest/delivery/pages/v1/shoes?gender=men&favorite-color=white' \
--header 'my-header-trait: my-header-trait-value'

Fetching all variants

The Delivery API can also return all page and component variants using the query parameter variants=all:

Java
  curl --location --request GET 'http://localhost:8080/magnoliaPublic/.rest/delivery/pages/v1/shoes?variants=all'  

Easier personalization in headless projects

Our low-code YAML configuration makes it easy for developers to create visitor traits that content authors can use to personalize experiences using their visual editor. Our implementation of headless personalization via the Delivery API then makes it possible for developers to consume clean, personalized content.

In this article, I've focussed on the changes to the delivery endpoint. Based on this foundation, we’ve also added full support for personalization to our headless Visual SPA Editor. You can learn more about it in the SPA documentation.

To learn more about headless personalization with Magnolia, check out our demo project on our git repository and the documentation, or ask our team for a demo.

Personalization in Headless Projects

About the Author

Jaroslav Simak Software Developer at Magnolia

Read more