The eZ Systems Recommendation Bundle extends the functionality of eZ Platform with a Personalization Solution, powered by YOOCHOOSE. It allows you to track the way visitors use your website and recommends content based on their behavior. You can also use the personalized search (content suggestions) and personalized newsletter features (embedding personalized content in your newsletters).
Personalization Bundle v1
This page covers Recommendation Bundle v2, which is the latest version, used with all current releases of eZ Platform. If you are still using Recommendation Bundle v1, contact firstname.lastname@example.org if you need information.
1. Run composer require¶
Run the following from your eZ Platform installation root:
2. Enable the bundle¶
Enable the bundle in
1 2 3 4
3. Import additional routing¶
Import additional routing by adding the following lines to your
1 2 3
Legacy support is disabled by default. To enable the legacy search engine (requires
ezpublish-kernel bundle) copy these service definitions to your
app/config/services.yml file and uncomment them:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
4. Register a Personalization Solution account¶
Register an account (a so-called customerID) with your eZ Sales manager. If you want to use the open source version of eZ Platform without any subscription please send an email to email@example.com.
5. Allow public HTTP(S) access¶
Allow public HTTP(S) access to the recommendation bundle API (
IP whitelisting when public access is not possible
The Personalization Solution servers need to access the API of an eZ Platform installation in order to continuously sync content. If it's not possible to allow public access, the following IP Addresses can be used for whitelisting on (for example), a firewall.
126.96.36.199, 188.8.131.52, 184.108.40.206, 220.127.116.11, 18.104.22.168, 22.214.171.124, 126.96.36.199
If BASIC AUTH is required by policy
If the company policy is to use BASIC AUTH on the API interfaces, you need to add some specific configuration.
You probably have some access restrictions on your site defined in app/config/security.yml
1 2 3 4 5 6 7 8 9 10
Create a user with the name of the CustomerID and a password which is the license key in your local security provider. This user must have access granted on the URLs provided by the bundle API (see above).
In order to tell the recommender to use this user and password to request resources on the eZ Platform instance, you can configure this as follows (an example file is available in the bundle under
1 2 3 4 5 6 7 8 9
Place this in a settings file which won't be affected by an update to the Recommendation bundle via Composer.
1. Define what content should be tracked and exported¶
Visitor events (clicks, buys, ...) on the site need to be sent to the Personalization Solution for the recommendations to be calculated. The content types that are marked to be tracked are also exported to the Personalization Engine. Please note that you can only recommend what you track!
By defining the Content Types in the local
app/config/config.yml file, the content will be initially exported by a script. After this, it will be kept in sync with the Personalization Solution every time a change occurs in the eZ Platform back office.
The bundle's configuration is SiteAccess-aware. This is an example of the settings (in
1 2 3 4 5 6 7 8 9
The following parameters need to be included in the settings file:
||Your YOOCHOOSE customer ID.|
||Your YOOCHOOSE license key.|
||The URI your site's REST API can be accessed from.|
||Content Types on which the tracking script will be shown.|
If the content's author or image are stored in a different Field, you can specify its name in the
1 2 3 4 5 6 7 8
In case a content owner ID is missing, you can set up the default content author in the
You can edit advanced options for the Personalization Engine using the following settings:
1 2 3 4 5 6 7 8
Note: changing any of these parameters without a valid reason will break all calls to the Personalization Engine.
EzSystemsRecommendationBundle delivers a Twig extension which helps integrate the tracking functionality into your site. Place the following code snippet in the HEAD section of your header template:
1 2 3
How tracking works
2. Check if the bundle provides REST data¶
You can verify the import controller of the bundle by calling the local API. You should use the 'Accept' header and may need to add an 'Authorization' header if authentication is required.
To check if the
content interface is working as expected, try this URI:
1 2 3
Additionally you should check if the
contenttypes interface is working as well by calling the following URI:
1 2 3
Both interfaces are supposed to provide content data in JSON format.
The only difference is the size of the content array in the
content interface one Content item is returned, for the
contenttypes interface many are returned.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
Running a full content export¶
Exporting content is crucial for providing recommendations
If the content export does not work, your recommendations will not work as well. Required data like URIs, titles etc. will be missing and cannot be delivered in the recommendation response.
After defining which Content Types should be tracked and recommended you can start the full export by executing the following command:
With this command, the bundle exporter will collect all content related to the SiteAccesses of this customerID and store it in files (1).
After finishing, the systems will send a POST request to the
webHook endpoint and inform the personalization engine to fetch new content (2).
An internal workflow is then triggered (3) so that the generated files are downloaded (4) and imported in the personalization engine's content store (5).
Please be patient, as this can take up to a couple of minutes.
Changing Content Types for recommendations
If the Content Types to be recommended are changed, a full export needs to be started again by running the
php app/console ezreco:runexport command.
Checking if the full context export was stored in the recommender engine¶
There are three ways to check if content was transferred and stored successfully in the recommender engine:
REST request to the recommender's content store¶
To get the content of an imported item you can request the following REST resource
This way requires BASIC Auth. BASIC Auth username is the customerID and the password is the license key.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
You can log in to admin.yoochoose.net, switch to the Item Import tab and check if a FULL import was successful.
Personalized Search Requests¶
Since the search functionality is included by default, you can also create and invoke a search request to look for content that matches certain criteria. The easiest way to do this is to assign the contentID to the request parameter
q. Make sure that the contentID is at least 2 chars long (for example,
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
Incremental content export¶
Every time an editor creates, updates or deletes content in the backoffice (1), a notification is sent to https://admin.yoochoose.net informing that a content change has occured (2). The yoochoose service will also notify other components of the recommendation engine (3) and it will eventually fetch the affected content (4) and update it internally (5).
This mechanism allows the content in the personalization engine to be always in sync with the content on eZ Platform.
Recommendations are fetched and rendered asynchronously in the client, so there won't be any additional load on the server. Therefore it is crucial to check if the content export has been successful, as e.g. deeplinks and image references are included. If the export is NOT successful, the personalization engine will not have the full content information. This will break the recommendations. Even if the recommendations are displayed, there is a big chance they won't have images, titles or deeplinks.
In order to allow displaying recommendations on your site, you must add some code which will integrate the recommender engine (with your site). This can be achieved with a few steps (assuming that
EzSystemsRecommendlationBundle is properly configured and enabled in
1 2 3 4 5 6
Place a dedicated Twig helper in the place where you want to display recommendations:
1 2 3 4 5 6 7 8
||int||In content-based views the Twig variable holding the content ID (the content you want to get recommendations for).|
||string||Scenario used to display recommendations. You can create custom scenarios in the Personalization Engine's dashboard.|
||int||Number of recommendations to fetch.|
||string||Content Type you are expecting in response, e.g. article.|
||string||Handlebars template name. Your templates are stored in the
||array||Fields which are required and will be requested from the recommender engine. These Field names are also used inside Handlebars templates.|
Sample integration can take the following form:
1 2 3 4 5 6 7 8
You can also bypass named arguments using standard value passing as arguments.
Recommendation responses contain all content data which is requested as attribute in the recommendation call. These 'attributes' of the response can be used in Handlebars templates to render and style recommendations. For example, the GET request:
delivers the following response if the content Fields were previously (and successfully) exported by the export script.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
Displaying image variations¶
Displaying image variations is not currently supported out of the box.
If you want to access a specific image variation through API, you need to add the
image parameter to the request URL with the name of the variation as its value.
For example, to retrieve the
rss variation of the image, use:
"Console error: eZ is not defined"¶
If you see this error in the console of your browser's debugger you need to rerun the asset installer:
Authentication does not work¶
If authentication fails although you added a user in your local directory please check if you used double quotes around the username in the export settings.
Requested content type is not supported (CONFLICT)¶
When fetching recommendations you get a message that the requested content type is not supported (CONFLICT). Take a look at the scenario configuration in the Admin Dashboard and check if the input and output types are properly set.
Most operations are logged via the
ez_recommendation Monolog channel. To log everything about Recommendation to
dev.recommendation.log, add the following to your
1 2 3 4 5 6 7
You can replace
debug for more verbosity.