Targeting and Personalization

Pimcore 5.1 introduces completely new targeting and personalization features by implementing a server side targeting engine which can be tightly integrated into other server side components such as the customer management framework or the ecommerce framework.

The following section describes the technical concepts and aspects of the Pimcore targeting enginge. For usage description and feature listing see your user docs first.

NOTE: the new targeting engine is incompatible to the targeting feature which was shipped with Pimcore before 5.1. See Migrating from the existing Targeting Engine for further details.

Basic concepts

VisitorInfo and Visitor ID

When a request is handled, the targeting engine first creates a new VisitorInfo instance. This instance is a data container which will be used throughout the targeting process to store and pass data between different components of the system.

See Visitor Info for details.

Target Rule Matching

After building the VisitorInfo and resolving the visitor ID, the matching engine processes every defined targeting rule. Based on the rule's scope a rule might be skipped (e.g. a session rule is applied only once per session). Every condition gets the instance of the VisitorInfo and needs to decide if it matches its configured data.

To fetch additional data about the visitor, a condition can request data from one or more DataProvider implementations. As an example the Device data provider is able to resolve and cache device info from the user agent string by using the DeviceDetector library. The Operating System condition just defines the Device data provider as dependency and can rely on the device data being added the the VisitorInfo before matching. The targeting engine takes care of requesting data from a data provider only once per request, even if multiple conditions rely on its data.

If a rule matches, a list of actions is applied. Example actions are issuing a redirect or assigning a target group to the current visitor. Actions (which are executed by action handlers) can request data from data providers in the same way as conditions.

Targeting Storage

Some data needs to be persisted between requests. To do so, the targeting implementations makes use of a TargetingStorage which implements a key-value store for targeting data. Data can be set for the visitor (valid for the whole lifetime of a visitor) or for the session level. When storing data to an external storage, the previously resolved visitor ID is used to store data for a specific visitor.

Examples for data which is persisted to storage:

• assigned target groups - either set from targeting rules or automatically tracked when visiting a document which defines target groups to apply (as set on the document settings tab)
• already matched rules with session scope to avoid to repeatedly execute them for the same visitor
• first request to site in the current session (e.g. to calculate the time on site)

For further details see Targeting Storage.

Content Targeting

After matching all rules, a VisitorInfo may have different assigned target groups. When rendering a document which has targeted content for multiple target groups, the following logic is applied to determine which version to use for the current visitor:

• If the visitor has only one assigned target group and content exists for that target group, the personalized version for that target group will be used
• If the visitor has multiple assigned target groups, they will be sorted by their assignment count. The first target group in the sorted list which has personalized content for the document will be used.

This logic is repeated for every document and sub-request. This means you can show personalized content for a given target group on a document, but have content for different target groups in snippets or renderlets rendered on the same page.

You can see which target groups were applied to which document in the profiler. As you can see in the screenshot below, the main document used the target group basketball while the footer snippet was rendered with the target group female.

Manually applying Content Targeting

The logic defined above can be applied to any document. Documents which are loaded through Pimcore's standard routing and rendering features will be automatically configured, but you also manually configure any document to use personalized content by using the DocumentTargetingConfigurator service. As example, when handling a document inside a controller which is registered as service:

<?php

namespace AppBundle\Controller;

use Pimcore\Controller\FrontendController;
use Pimcore\Model\Document;
use Pimcore\Targeting\Document\DocumentTargetingConfigurator;

class ContentController extends FrontendController
{
    public function pageAction(DocumentTargetingConfigurator $targetingConfigurator)
    {
        // load any document
        $document = Document::getByPath('/my/page');

        // configure personalized content based on resolved target groups
        // and available personalized content on the document
        $targetingConfigurator->configureTargetGroup($document);
        
        //...
    }
}

Extending the Targeting Engine

The targeting engine is designed in a way to be easily extendable by third party code to extend and customize the engine's behaviour.

See the following resources for further details:

• Conditions
• Data Providers
• Action Handlers
• Targeting Storage
• Frontend Javascript

Debugging Targeting Data

As shown above, targeting date is added to the Symfony profiler. In addition you can enable a dedicated targeting toolbar which also works outside the dev environment when you are logged into the admin interface.

The toolbar is only shown if a pimcore_targeting_debug cookie exists and is set and its value evaluates to true. You can set the cookie with the following bookmarklet (just drag the link to your bookmarks bar):

• Enable Pimcore Targeting Toolbar

Opt-out from targeting

You can give the user the possibility to opt-out from targeting at any time, by setting the following cookie: pimcore_targeting_disabled=1.