Requesting personalized content with the delivery endpoint

This page describes configuration aspects essential for requesting personalized content with the Delivery API.

Installation

Personalization in the Delivery API is a DX Core feature provided by the Personalization module in version 2.1.0 and later.

If you wish to use the feature, you need to have the following submodules in your webapp. By default, they are not bundled with our webapps.

<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-rest</artifactId>
  <version>2.1.0</version>
</dependency>
<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-traits</artifactId>
  <version>2.1.0</version>
</dependency>

To be able to use personalization in the Delivery API, you should:

  1. Add the Blossom dependency (magnolia-personalization-blossom-compatibility) only if you are using the Blossom modules in your project:

    <dependency>
      <groupId>info.magnolia.personalization</groupId>
      <artifactId>magnolia-personalization-blossom-compatibility</artifactId>
      <version>2.1.0</version>
    </dependency>
  2. 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.0</version>
          </dependency>
    
      </dependencies>
    
      <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:

/my-module/restEndpoints/delivery/pages_v1.yaml
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

Headless personalization and caching

For headless p13n to work correctly with content caching in Magnolia, you have to set /modules/cache/config/contentCaching/<your-configuration>/cachePolicy@includePersonalizedDescendants to true.

By setting this property, the dynamic page caching function is turned off.

Currently, Magnolia does not support caching for different headers or cookies. Therefore it is impossible to specify for which headers (or cookies) a response should be cached.

An improvement addressing this issue has been filed as MGNLCACHE-245.

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:

  • date

  • cookies

  • country

  • visitor

These traits are now provided by the magnolia-personalization-compatibility submodule.

Due to session security restrictions, the country trait can only be used if Magnolia and an SPA application are on the same domain.

<light-module>/traits/color.yaml
$type: cookieTrait
# name: is omitted as it is taken from the name of the yaml file

Example 2: Header type trait called gender

<light-module>/traits/gender.yaml
$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&bull; Leather mix upper<br />\n&bull; Recycled polyester, polyester and polyurethane lining<br />\n&bull; Recycled polyester, polyester and polyurethane insock<br />\n&bull; Natural rubber outsole<br />\n&bull; Cupsole<br />\n&bull; Tommy Hilfiger branding<br />\n&bull; Tommy Hilfiger flag at heel<br />\n<br />\nShape &amp; fit<br />\n<br />\n&bull; Low-top<br />\n&bull; Lace-up<br />\n&bull; Almond toe<br />\n<br />\nComposition &amp; care<br />\n<br />\n&bull; 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 REST delivery endpoint will return personalized content based on the traits of the current request and session.

Related topics
Feedback