-
Jaroslav SimakSoftware Developer, Magnolia
Introducing Headless Personalization
Magnolia in action
Take 12 minutes and a coffee break to discover how Magnolia can elevate your digital experience.
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:
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:
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:
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:
"@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:
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:
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.
