Requesting personalized content with the delivery endpoint
This page describes configuration aspects essential for requesting personalized content with the Delivery API. Personalization in the Delivery API is a DX Core feature provided by the Personalization module in version 2.1.0 and higher.
To be able to use personalization in the Delivery API, you should: |
-
Add the Blossom dependency (
magnolia-personalization-blossom-compatibility
) only if you are using the Blossom modules in your project:<dependency> <groupId>info.magnolia.rest</groupId> <artifactId>magnolia-personalization-blossom-compatibility</artifactId> <version>3.0-SNAPSHOT</version> (1) </dependency>
1 Should you need to specify the module version, do it using <version>
. -
Make sure that in the content of your
pom.xml
for your webapp you include the following two dependencies if your project is generated from the Magnolia webapp archetype:... <dependencies> ... <!-- include p13n for rest --> <dependency> <groupId>info.magnolia.personalization</groupId> <artifactId>magnolia-personalization-rest</artifactId> <version>2.1.1</version> </dependency> </dependencies> ...
If you use personalization version 2.1.0, you also need to add the following dependencyManagement into your webapp’s
pom.xml
file.... <dependencyManagement> <dependencies> <!-- include dependency management for p13n 2.1.0 --> <dependency> <groupId>info.magnolia.personalization</groupId> <artifactId>magnolia-personalization-parent</artifactId> <version>2.1.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> ...
Configuration
Delivery of personalized content is based on sending one or more traits to an endpoint configured to handle personalized REST requests.
Endpoint configuration
In the configuration of an endpoint that is expected to handle personalized content, you must set the personalized
property to true
. See line 7 in the following example:
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: website
limit: 25
depth: 5
includeSystemProperties: false
bypassWorkspaceAcls: true
personalized: true
nodeTypes:
- mgnl:page
childNodeTypes:
- mgnl:area
- mgnl:component
Personalization and root nodes
No personalization variants are returned if you address a root node, fo example:
host:port/.rest/delivery/pagesnav/v1/
If you requested a subpath of the root (host:port/.rest/delivery/pagesnav/v1/start
), personalized content variant would be returned.
Sending a request to a URI that ends with just the endpointPath
invokes the Query nodes method. It is irrelevant if you add the trailing slash (/
) or omit the slash to the endpointPath
.
In this case, the REST endpoint behaves as a query. That’s why we introduced the @nodes
handle that you can use to request a root node with personalized content.
Headless personalization and caching
For headless personalization to work correctly with content caching in Magnolia, you have to set /modules/cache/config/contentCaching/<your-configuration>/cachePolicy@includePersonalizedDescendants
to true
.
By configuring this property, the dynamic page-caching function is disabled.
Magnolia does not currently support caching for different headers or cookies. Therefore, it is impossible to specify for which headers or cookies a response should be cached. See MGNLCACHE-245 for the upcoming improvement. |
Trait types and their configuration
To request personalized page or component variants, you need to configure at least one personalization trait. Additionally, a personalized page or component variant must be defined. The variant will be matched with a configured trait.
Once a trait has been configured, it can be sent in a REST request in one of the following forms:
-
A cookie.
-
A request header.
-
A request parameter (a query string of a GET request or body parameters of a POST request).
Traits are matched strictly by their names and values. In a trait configuration part of a module, trait rule and value fields must be preconfigured as single-value fields, for example as a textField
or a comboBoxField
. See the two example trait configurations below.
Any module can register a trait. For more details and trait configuration properties, see Registering a trait. The traits that were present in the older (pre-2.1) versions of the Personalization module can also be used:
These traits are now provided by the Due to session security restrictions, the |
Example 1: Cookie type trait called color
$type: cookieTrait
# name: is omitted as it is taken from the name of the yaml file
Example 2: Header type trait called gender
$type: headerTrait
ruleField:
$type: comboBoxField
name: value
datasource: &datasource
$type: optionListDatasource
options:
- name: male
value: male
- name: female
value: female
valueField:
$type: comboBoxField
datasource: *datasource
Example p13n REST request and response
The following example is based on trait and content configurations available in the demo-rest-p13n
, a light module showcasing personalization over REST in Magnolia. For more information how to install the demonstration module, see the README.md
file in it.
- URL with a p13n parameter
http://localhost:8080/magnoliaAuthor/.rest/delivery/pages/v1/shoes/men?favorite-color=white
- JSON response
{
"@name": "men",
"@path": "/shoes/men",
"@id": "881d5dc8-90c9-4175-88fe-0a310c9bfd35",
"@nodeType": "mgnl:page",
"hideInNav": "false",
"navigationTitle": "Men",
"title": "Tommy Hilfiger | Men Shoes",
"noCache": "false",
"main": {
"0": {
"@name": "0",
"@path": "/shoes/men/main/0",
"@id": "1b64e04e-f65a-4f5a-a27e-d08bc0ba4218",
"@nodeType": "mgnl:component",
"@variantNodeName": "variant-0",
"@variantPath": "/shoes/men/main/0/variants/variant-0",
"link": {
"@name": "Basket-Leather-Cupsole-Trainers",
"@path": "/tommy-hilfiger/men/Basket-Leather-Cupsole-Trainers",
"@id": "55310089-2b40-406b-8292-3374f393c588",
"@nodeType": "mgnl:shoe",
"name": "Basket Leather Cupsole Trainers",
"brand": "c547f96e-d14d-42ef-b450-4e15460c56f7",
"description": "<p>With an understated upper, these trainers get their standout value from a substantial cupsole featuring eye-catching striped detail.<br />\n<br />\nHighlights<br />\n<br />\n• Leather mix upper<br />\n• Recycled polyester, polyester and polyurethane lining<br />\n• Recycled polyester, polyester and polyurethane insock<br />\n• Natural rubber outsole<br />\n• Cupsole<br />\n• Tommy Hilfiger branding<br />\n• Tommy Hilfiger flag at heel<br />\n<br />\nShape & fit<br />\n<br />\n• Low-top<br />\n• Lace-up<br />\n• Almond toe<br />\n<br />\nComposition & care<br />\n<br />\n• 75% leather, 25% polyesterStyle #: FM0FM03432</p>\n",
"image": "jcr:2b2c33be-81cc-4262-a01d-60c2d8d90866",
"@nodes": []
},
"@nodes": []
},
"@name": "main",
"@path": "/shoes/men/main",
"@id": "84c301e0-ebe9-4902-af98-140bead1645d",
"@nodeType": "mgnl:area",
"@nodes": [
"0"
]
},
"footer": {
"@name": "footer",
"@path": "/shoes/men/footer",
"@id": "95141d5d-ccc2-4e1c-bc98-4a537379b5b6",
"@nodeType": "mgnl:area",
"@nodes": []
},
"@nodes": [
"main",
"footer"
]
}
Personalization of an SPA page
The Visual SPA Editor fully supports the personalization features of the Pages app. Authors can:
-
create variants of pages or component,
-
choose audiences for them, and
-
test the results in the Preview app.
The Delivery API will return personalized content based on the traits of the current request and session.
For more details, see Personalization of headless SPA projects.