Recommendation¶
ezrecommendation-client adds a personalization solution to eZ Platform.
It enables you to track the way visitors use your website and recommends content based on their behavior.
More information
This page covers the ezrecommentation-client, which communicates with the Recommendation engine.
To learn more about the engine itself, see Personalization.
Installation¶
ezrecommendation-client
is provided in a separate package and is not included in eZ Platform by default.
To use it, you need to install the package:
1. Install and enable the bundle¶
Run composer require from your eZ Platform installation root:
1 2 | |
Next, enable the bundle in app/AppKernel.php:
1 2 3 4 | |
2. Import additional routing¶
Import additional routing by adding the following lines to your routing.yml file:
1 2 3 | |
3. Register an eZ Personalization account¶
Register an account (customerID) with your eZ Sales manager.
Tip
If you want to use the Recommendation engine with the open source version of eZ Platform, send an email to support@ibexa.co.
4. Allow public HTTP(S) access¶
Allow public HTTP(S) access to the recommendation bundle API (<yourdomain>/api/ezp/v2/ez_recommendation/**)
IP whitelisting
The Recommendation engine 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.
54.229.102.177, 54.171.192.161, 54.77.201.13, 52.215.22.234, 52.18.150.96, 52.17.60.35, 52.17.36.104
If BASIC AUTH is required by policy
If your organization's policy is to use BASIC AUTH on the API interfaces, you need to add specific configuration.
You can define access restrictions on your site 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 Resources/config/default_settings.yml):
1 2 3 4 5 6 7 8 9 10 11 12 13 | |
With the user authentication method, login must be the same as customer_id and password must be the same as license_key.
Place this in a settings file which won't be affected by an update to the bundle.
Configuration¶
Set up Content Type tracking¶
Visitor events (clicks, buys, etc.) on the site need to be sent to the Recommendation engine for the recommendations to be calculated. The Content Types that are tracked are also exported to the engine. Tracking Content Types is required for displaying recommendations.
You define Content Types to track in the local app/config/config.yml file.
The content will then 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 config.yml):
1 2 3 4 5 6 7 8 9 | |
Tip
It is recommended to provide your host_uri, customer_id and license_key through environment variables: '%env()%'.
| Parameter | Description |
|---|---|
authentication.customer_id |
Your customer ID. |
authentication.license_key |
Your license key. |
host_uri |
The URI your site's REST API can be accessed from. |
included_content_types |
Content Types on which the tracking script will be shown. |
random_content_types |
Content Types which will be returned when the response from the Recommendation engine contains co content. |
Advanced configuration¶
If the Content item's intro, author or image are stored in a different Field,
you can specify its name in the parameters.yml file:
1 2 3 4 5 6 7 8 9 10 11 12 | |
In case a content owner ID is missing, you can set up the default content author in the default_settings.yml file:
1 2 3 4 | |
You can edit advanced options for the Recommendation engine using the following settings:
1 2 3 4 5 6 7 8 9 10 11 12 13 | |
Caution
Changing any of these parameters without a valid reason will break all calls to the Recommendation engine.
Enable tracking¶
The EzRecommendationClientBundle delivers a Twig extension
which helps integrate the user tracking functionality into your site.
Place the following code snippet in the <head> section of your header template:
1 2 3 | |
How tracking works
For more information about tracking in general, see (Tracking API)](developer_guide/tracking_api.md) and about the generic asynchronous JavaScript tracker.
Checking 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 endpoint is working as expected, perform the following request:
1 2 3 | |
Additionally you should check if the contenttypes endpoint is working with the following request:
1 2 3 | |
The content endpoint returns one Content item and the contenttypes endpoint returns many.
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 | |
Exporting content information¶
To get recommendations you must first export the content information to the Recommendation engine.
After defining which Content Types should be tracked and recommended,
start the full export.
You can do it with the ezrecommendation:export:run command or by accessing the http://<yourdomain>/api/ezp/v2/ez_recommendation/ URL/endpoint.
1 2 3 4 5 6 | |
1 | |
The bundle exporter collects all content related to the SiteAccesses of this customerID and stores it in files (1).
After finishing, the systems sends a POST request to the webHook endpoint and informs the Recommendation 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 Recommendation engine's content store (5).
The export process can take a few minutes.
Re-exporting modified Content Types
If the Content Types to be recommended are changed, you need to perform a new full export
by running the php bin/console ezrecommendation:export:run command again.
Checking export results¶
There are three ways to check if content was transferred and stored successfully in the Recommendation engine:
REST request to the recommender's content store¶
To get the content of an imported item you can request the following REST resource:
GET https://admin.yoochoose.net/api/<your_customer_id>/item/<your_content_type_id>/<your_content_id>
This way requires BASIC Auth. BASIC Auth username is the customerID and the password is the license key.
Example response
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 | |
Recommender Backend¶
You can log in to admin.yoochoose.net, switch to the Item Import tab and check if a FULL import was successful.
Subsequent content exports¶
The Recommendation engine is automatically kept in sync with the content in eZ Platform.
Every time an editor creates, updates or deletes content in the Back Office (1), a notification is sent to https://admin.yoochoose.net (2). The recommendation service also notifies other components of the Recommendation engine (3) and it eventually fetches the affected content (4) and updates it internally (5).
Displaying recommendations¶
Client-based recommendations
Recommendations are fetched and rendered asynchronously in the client, so there is no 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 Recommendation 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 display recommendations on your site, you need to add the following JavaScript assets to your header template:
1 2 3 | |
This file is responsible for sending notifications to recommendation API after the user clicks on a tracking element.
To render recommended content, use a dedicated showRecommendationsAction from the RecommendationController.php:
1 2 3 4 5 6 7 8 | |
Tip
To check if tracking is enabled on the front end, use the ez_recommendation_enabled() Twig function.
You can wrap the call to the RecommendationController with:
1 2 3 4 5 | |
Parameters¶
| Parameter | Type | Description |
|---|---|---|
contextItems |
int | ID of the content you want to get recommendations for. |
scenario |
string | Scenario used to display recommendations. You can create custom scenarios in the Recommendation engine's dashboard. |
outputTypeId |
string | Content Type you are expecting in response, e.g. blog_post. |
limit |
int | Number of recommendations to fetch. |
template |
string | Template name. |
attributes |
array | Fields which are required and will be requested from the Recommendation engine. These Field names are also used inside Handlebars templates. |
You can also bypass named arguments using standard value passing as arguments.
Custom templates
If you want to use a custom template for displaying recommendations,
it must include event_tracking.html.twig:
{% include 'EzRecommendationClientBundle::event_tracking.html.twig' %}.
Recommendation responses contain all content data which is requested as attribute in the recommendation call. This response data can be used in templates to render and style recommendations.
For example, the following GET request should deliver the response below if the content Fields were previously exported by the export script.
GET https://reco.yoochoose.net/api/v2/<your_customer_id>/someuser/popular.json?contextitems=71&numrecs=5&categorypath=/&outputtypeid=<your_content_type>&attribute=name,author,uri,image
Example response
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 | |
Image variations¶
Displaying image variations is not currently supported out of the box.
You can work around this limitation by creating your own template (based on recommendations.html.twig).
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:
/api/ezp/v2/ez_recommendation/v1/contenttypes/16?lang=eng-GB&fields=title,description,image,intro,name&page=1&page_size=20&image=rss
Troubleshooting¶
Logging¶
Most operations are logged via the ez_recommendation Monolog channel.
To log everything about Recommendation to dev.recommendation.log, add the following to your config.yml:
1 2 3 4 5 6 7 | |
You can replace info with debug for more verbosity.