Development Documentation
The following section describes the technical concepts and aspects of the Pimcore targeting engine. For usage description and feature listing see your user docs first.
Setup
You need to enable targeting either by setting the following config
pimcore_personalization:
targeting:
enabled: true
or using the cookie pimcore_targeting_enabled=1
.
if you'd like to use geo-related conditions in your targeting rules it's necessary to configure the underlying data provider first.
Configuring the MaxMind GeoIP Data Provider
Follow the official instructions for obtaining and updating the GeoIP database.
Store the database file at the location of your choice, the default location used by geoipupdate is /usr/share/GeoIP/GeoLite2-City.mmdb
Set the path to the database file in your parameters.yaml
to enable the geo support in Pimcore:
pimcore.geoip.db_file: /usr/share/GeoIP/GeoLite2-City.mmdb
Basic concepts
Concept | Description |
---|---|
VisitorInfo | Contains run-time information on the current visitor and is used by all conditions and action handlers to collect/apply data. |
DataProvider | Can be used by other components such as conditions to fetch data about the current visitor. E.g. the Device data provider loads device info from the user-agent string. Data is only loaded on demand if really needed by a component. |
Condition | A condition which is being matched. Conditions are configured in the Admin UI for global targeting rules. |
ActionHandler | A targeting rule can have one or multiple actions which are executed when its conditions match. These actions are executed by an action handler. E.g. the Redirect action handler creates a RedirectResponse which is used to redirect the visitor to another page. |
Storage | Where data about the visitor is persisted to. Each storage implementation supports storage for the session and the visitor scope. Session scoped data is only valid for the current session - either defined by a expiry time or by technical implications of the storage (e.g. the Cookie storage just sets a session cookie for the session storage). Visitor data is valid for the lifetime of the visitor and should be persisted, but depending on the used storage (e.g. Session Storage) this might not be possible. Different storages exist, e.g. cookie, JWT signed cookie, DB, session and redis which all have their advantages and disadvantages. |
Targeting Rule | A condition/action combination executing one or more actions if a set of conditions match (similar to pricing rules in the ecommerce framework). Targeting rules are usually executed on every request but depending on their scope (hit, visitor, session, session with variables) this can be limited. |
Target Group | An entity which is used to target content for. A document/snippet can define personalized content for a specific target group (e.g. a special banner for a target group "Outdoor Interested"). By matching targeting rules and by configuring target groups to be tracked when visiting documents, a visitor will be assigned a list of target groups (they will be stored to storage and be added to the VisitorInfo object at runtime). When rendering the document, a DocumentTargetingConfigurator selects the content which matches best for the target groups which are available on the VisitorInfo . |
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 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.