Recom= mendation Bundle integrates the YOOCHOOSE recommendation engine into eZ= .
=20
The Recommendation Bundle extends the functionality of eZ with a recomme= ndation engine, powered by YOOCHOOSE. It allows you to track the way v= isitors use your website and suggests recommended content to them based on = their behavior.
Support
Stable versions of this bundle <= span>is officially supported by eZ = as of version 1.0.0, <= /span>for users with a eZ Ent= erprise and Yoochoose subscription.
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.0.x release):
php composer.phar require ezsystems/recommendation-bundle:~1.0.0=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.
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 your bundle is built on top of th=
e DemoBundle this is page_head.html.twig):
{% 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_setti=
ngs.yml file delivered with this bundle). Here you can define fo=
r 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 (if your bundle is built on top of the DemoBundle this is pag=
e_head_script.html.twig):
{% 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.=
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.
eZ Studio =C2=A9 1999-20= 15 eZ Sy= stems AS and others