The Recommendation Bundle extends the functionality of eZ Publish with a= recommendation engine, powered by YOOCHOOSE. It allows you to track t= he way visitors use your website and suggests recommended content to them b= ased on their behavior.
The Recommendation Bundle is installed in a similar way as any other Sym= fony bundle.
This bundle is independent from the ezrecommendation extension used in l= egacy, and does not require it.
1. Run the following from your eZ Publish installation = root (here with most recent 1.x release):
composer require --no-update ezsystems/recommendation-bundle:^1.0.0 composer update --prefer-dist=20
2. Enable the bundle in ezpublish/EzPublishKernel=
.php:
$bundles =3D array(
// existing bundles
new EzSystems\RecommendationBundle\EzSystemsRecommendationBundle()
);=20
3. Import additional routing by adding following lines =
to your routing.yml file:
recommendationBundleRestRoutes:
resource: "@EzSystemsRecommendationBundle/Resources/config/routing_rest=
.yml"
prefix: %ezpublish_rest.path_prefix%=20
The bundle's configuration is siteaccess aware. This is an example of se= ttings (config.yml):
ez_recommendation:
system:
default:
yoochoose:
customer_id: "12345"
license_key: "1234-5678-9012-3456-7890"
server_uri: "http://example.com"
recommender:
included_content_types: ["blog", "article"]=20
The following parameters need to be included in the settings file:
| Parameter | Description |
|---|---|
| yoochoose.customer_id | Your YOOCHOOSE customer ID. |
| yoochoose.license_key | Your YOOCHOOSE license key. |
| server_uri | The URI your site's REST API can be accessed fro= m. |
| recommender.included_content_types | Content Types on which the tracking script will = be shown. See Tracking below= for more information. |
If content's author or image are stored in different field, you can spec= ify it in parameters.yml:
ez_recommendation.field_identifiers:
{field fetched by controller (image or author)}
{content type}: {field with value}=20
For example:
ez_recommendation.field_identifiers:
author:
article: authors
image:
article: thumbnail
blog_post: main_image=20
You can select advanced options for YOOCHOOSE backend using the followin= g settings:
ez_recommendation:
api_endpoint: 'https://admin.yoochoose.net'
recommender:
api_endpoint: 'http://reco.yoochoose.net'
consume_timeout: 20
tracking:
api_endpoint: 'http://event.yoochoose.net'
script_url: 'cdn.yoochoose.net/yct.js'=20
Changing any of these parameters without a valid reason will break all c= alls to YOOCHOOSE. It can be useful to test the API by mocking the service,= or if you have a hosted version of YOOCHOOSE Recommendation service.
While Symfony dev environment keeps track of changes to yml files, prod = does not, so to make sure Symfony reads the new config we clear cache:
php app/console --env=3Dprod clear:cache=20
Your content structure must be mapped to the YOOCHOOSE domain model. Thi= s must be done in collaboration with YOOCHOOSE.
Public content is automatically indexed. When necessary= , eZ Publish will notify YOOCHOOSE of changes to content. Initial import is= to be managed with your YOOCHOOSE sales representative. Note that your ser= ver's REST API will need to be open to the YOOCHOOSE servers for indexing t= o be possible.
Events from the site need to be sent to YOOCHOOSE so that recommendation= s can be adapted to visitors. Tracking can be set up in multiple ways, depe= nding on existing constraints.
EzRecommendationBundle delivers a Twig extension which help=
s integrate the tracking functionality into your site.
1. Place the following snippet of code somewhere in the= HEAD section of your header template:
{% if content is defined %}
{{ yc_track_user(content.id) }}
{% endif %}=20
2. Configure settings under the recommender.inclu=
ded_content_types parameter (see the default_sett=
ings.yml file delivered with this bundle). Here you can define =
for which content types tracking script will be shown.
You can find more information about tracking in YOOCHOOSE documentation.
In order to allow displaying recommendations on your site you must add p= ortions of scripts which will integrate the recommender engine with your si= te.
Implementation is very easy and can be performed in just a few steps (as=
suming that the EzRecommendationBundle is properly configured =
and enabled in EzPublishKernel.php):
1. Add the following JavaScript assets to your header t= emplate:
{% javascripts
...
'%kernel.root_dir%/../vendor/components/handlebars.js/handlebars.min.js=
'
'@EzSystemsRecommendationBundle/Resources/public/js/recommendationtempl=
aterenderer.js'
'@EzSystemsRecommendationBundle/Resources/public/js/recommendationtempl=
atehelper.js'
'@EzSystemsRecommendationBundle/Resources/public/js/recommendationrestc=
lient.js'
%}=20
2. Place a dedicated Twig helper in the place where you= want to display recommendations:
{{ yc_show_recommendations(
contentId =3D content.id,
scenario =3D '',
limit =3D '',
contentType =3D '',
template =3D '',
fields =3D []
) }}=20
| Parameter | Type | Description |
|---|---|---|
| contentId | int | In content-based views the Twig variable holding= the content id (the content you want to get recommendations for). |
| scenario | string | Scenario used to display recommendations. You ca= n create custom scenarios at the YOOCHOOSE dashboard. |
| limit | int | Number of recommendations to show. |
| contentType | string | Content Types you are expecting in response. |
| template | string | HandleBars template name (your templates are sto=
red in the EzRecommendationBundle/Resources/public/views direc=
tory. Take a look at default.html.twig which includes a defaul=
t template that can be used to prepare customized versions). |
| fields | array | Fields which are required and will be requested = from the recommender engine. These field names are also used inside HandleB= ars templates. |
Sample integration can take the following form:
{{ yc_show_recommendations(
contentId =3D content.id,
scenario =3D 'popular',
limit =3D 5,
contentType =3D 'article',
template =3D 'default',
fields =3D ['ez_publishedDate', 'ez_url', 'title', 'image', 'author', '=
intro']
) }}=20
You can also bypass named arguments using standard value passing as argu= ments.
The item id is usually set to the viewed ContentId. Depending on require= ments, it can be set to a different value, in collaboration with YOOCHOOSE.=
If you want to access a specific image alias through API, you need to ad=
d the image parameter to the request url with name of ali=
as as its value, for example:
/api/ezp/v2/ez_recommendation/v1/contenttypes/16?lang=3Deng-GB&=
;fields=3Dtitle,description,image,intro,name&page=3D1&page_size=3D2=
0&image=3Drss
to retrieve the rss alias of the image.
V1.1=
As of v1.1 of the bundle, one more parameter is available: sa=
, which takes the siteaccess name and defines the siteaccess whose c=
ontent will be displayed.
Displaying image aliases
Displaying image variations defined with image aliases is not currently = supported out-of-the-box.
You can work around this limitation by creating your own template (based= on https://github.com/ezsystems/ezstudio= -demo/blob/master/app/Resources/EzSystemsRecommendationBundle/views/recomme= ndations.html.twig) or your own Twig extension (based on https://github.com/ezsystems/EzSystemsRecommendationBundle/blob/master/Tw= ig/RecommendationTwigExtension.php#L214).
Most operations are logged via the ez_recommendation Monolog channel. To log ever=
ything about Recommendation to dev.recommendation.log, add the following to=
your config.yml:
monolog:
handlers:
ez_recommendation:
type: stream
path: "%kernel.logs_dir%/%kernel.environment%.recommendation.=
log"
channels: [ez_recommendation]
level: info=20
info by=20
debug for more verbosity.