Personalization module

Personalization Bundled: DX Core

Edition DX Core

License

MLA

This module includes GeoLite2 data created by MaxMind, available from www.maxmind.com.

Issues

MGNLPN

Maven site

Personalization

Latest

3.0.3

Available on SPA/Headless

Yes

Personalization

Personalization refers to adapting content to a particular user according to his or her personal preferences, needs and capabilities. In order to do so, you first select a set of traits of a visitor or a visit, then compose rules using these traits to define what content is presented to which visitors and when.

Modules

Magnolia’s Personalization feature consists of the following modules.

  • Blossom-compatibility: Provides personalization of Blossom components.

  • Compatibility: Provides the 5 UI framework modules.

  • Components: Support for creating component variants.

  • Core: Personalization core.

  • Integration: Personalization support for creating page variants and fields for selecting traits and audiences.

    Since version 2.0, this submodule has been deprecated and its functions relocated to the Compatibility submodule.

  • Pages: Personalization integration for the Pages app.

  • Personas app: App for creating hypothetical visitors who represent your target audience.

  • Preview app: App for testing content delivery by impersonating a visitor.

  • REST: Personalization support for the Delivery API.

  • Segmentation app: Provides the Segments ppp for grouping visitors into segments.

  • Traits: Example traits country, date, cookie and visitor.

  • Widgetset: Widgetset for client-side extensions needed for the variant-selectors.

<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-compatibility</artifactId>
  <version>3.0.3</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-components</artifactId>
  <version>3.0.3</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-core</artifactId>
  <version>3.0.3</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-integration</artifactId>
  <version>3.0.3</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-pages</artifactId>
  <version>3.0.3</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-personas-app</artifactId>
  <version>3.0.3</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-preview-app</artifactId>
  <version>3.0.3</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-rest</artifactId>
  <version>3.0.3</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-segmentation-app</artifactId>
  <version>3.0.3</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-traits</artifactId>
  <version>3.0.3</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.personalization</groupId>
  <artifactId>magnolia-personalization-widget</artifactId>
  <version>3.0.3</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>.

Part of the module is also the magnolia-personalization-blossom-compatibility.

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>3.0.3</version> (1)
</dependency>
    1 Should you need to specify the module version, do it using <version>.

  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.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

See an overview of differences between FreeMarker and headless templating.

Components submodule

Nested variants occur when a page variant contains component variants. Control the ability for editors to create nested variants using the allowNestedVariants property on the module level configuration.

Node name Value

personalization-components

     config

         allowNestedVariants

false
Property Description

allowNestedVariants

optional, default is false

Allows you to create component variants inside a page variant if set to true.

Traits submodule

Provides out-of-the-box functionality for the following trait types:

  • All name-and-value based traits.

  • Cookie trait.

  • Header trait.

  • Request parameter trait.

Compatibility submodule

The magnolia-personalization-compatibility submodule provides the following pre-configured trait types, inherited from the older (pre-2.1) versions of the Personalization module:

  • Date

  • Country

  • Visitor

  • Cookies

Custom traits

Each trait has a configuration which can be adjusted. For configuration details, see the Registering a trait section on Creating custom traits page.

Enabling traits as URL parameters on the public instance

In Personalization module 3.0.4 and later, previewing traits as URL parameters on the public instance is disabled for security purposes.

You can still preview traits as URL parameters on the author instance.

If you want to test variant delivery on the public instance, you must enable it first. You can enable it through decoration or in the Configuration app.

If you do both, the decoration takes precedence over the Configuration app settings due to Magnolia’s resource loading order.

Decoration

  1. Decorate the Preview app under /<light-module>/decorations/personalization-preview-app/config.yaml.

  2. Set previewFilter to true.

    config.yaml
    previewFilter: true

Configuration app

  1. Open the Configuration app and go to /server/filters/preview.

  2. Add a property named enabled and set it to true.

📁 server

     📁 filters

         📁 preview

             ⬩ class

info.magnolia.personalization.preview.filter.PreviewFilter

             ⬩ enabled

true

Once enabled, you can pass traits as parameters in the URL on the public instance. This is a handy way to test scenarios that would otherwise be difficult to reproduce such as requesting the page from a Chinese IP address.

Use the following format:

http://example.com?<previewParameterPrefix><Parameter>=<value>
Table 1. URL parameters

previewParameterPrefix

Identifies the parameter as a preview parameter. Parameters used for personalization have a special prefix that sets them apart from other parameters. The default prefix is preview, for example previewPersona or previewCountry. You can configure the prefix string /modules/personalization-preview-app/config/previewParameterPrefix.

<Parameter>

Name of the parameter with first letter capitalized, for example Country or Date.

<value>

Parameter value in a valid format. The format depends on the parameter. For the country trait the value is a two-letter country code (gb, cn) and for a date it is a timestamp written as yyyy-mm-dd-hh-mm-ss such as 2019-05-26-00-00-00).

Example: Visitor from China on May 26, 2019:

http://localhost:8080/magnoliaPublic/travel/festivals.html?previewCountry=cn&previewDate=2019-05-26-00-00-00

The image of the Dragon Boat Festival a visitor from China on May 26, 2019 sees

Issues

Missing CountryVoter

You may encounter the following issue:

2024-09-18 15:30:30,533 WARN  agnolia.transformer.ClassPropertyBasedTypeResolver: Encountered the 'class' property but failed to resolved the type from its value: [info.magnolia.personalization.geoip.CountryVoter]
java.lang.ClassNotFoundException: info.magnolia.personalization.geoip.CountryVoter

Solution

  1. Add the following dependency to your webapp:

      <dependency>
        <groupId>info.magnolia.personalization</groupId>
        <artifactId>magnolia-personalization-compatibility</artifactId>
        <version>${personalization.version}</version>
  </dependency>

  2. If needed, copy the related configuration from /modules/personalization-traits.

Related topics
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules