This bundle integrates Recommendation services into eZ Platform. It supports the YooChoose recommender at this moment.

Work in progress This Bundle is work in progress, and support is restricted to pull request (contribution) directly on this repository until it reaches v1.0. After that, it will officially be supported by eZ for users with eZ and Yoochoose subscription.

• PHP 5.4.4
• eZ Publish 5.4.1/2015.01 or above, with the REST API configured to use sessions and publicly open to the YooChoose servers.
• A YooChoose license

This bundle is independent from legacy's ezrecommendation extension, and doesn't require it.

This package is available via composer, so the instructions below are similar to how you install any other open source Symfony Bundle.

Run the following from your eZ Publish installation root (pick most recent release, example here is last one as of this writing):

php composer.phar require ezsystems/recommendation-bundle:~1.0@beta

Enable the bundle in ezpublish/EzPublishKernel.php:

$bundles = array(
    // existing bundles
    new EzSystems\RecommendationBundle\EzSystemsRecommendationBundle()
);

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%

Keep in mind, that legacy support is disabled by default. To enable legacy search engine (requires ezpublish-kernel bundle) uncomment these lines in bundle services.yml:

#    ez_recommendation.legacy.search_engine:
#        class: ezpSearchEngine
#        factory_class: EzSystems\RecommendationBundle\eZ\Publish\LegacySearch\LegacySearchFactory
#        factory_method: build
#        arguments: [@ezpublish_legacy.kernel]
#
#    ez_recommendation.legacy.recommendation_search_engine:
#        class: EzSystems\RecommendationBundle\eZ\Publish\LegacySearch\RecommendationLegacySearchEngine
#        arguments:
#            - @ez_recommendation.client.yoochoose_notifier
#            - @ez_recommendation.legacy.search_engine
#
#    ez_recommendation.legacy.search_configuration_mapper:
#        class: EzSystems\RecommendationBundle\eZ\Publish\LegacySearch\ConfigurationMapper
#        arguments:
#            - @ez_recommendation.legacy.recommendation_search_engine
#            - @ezpublish.siteaccess
#        tags:
#            - { name: kernel.event_subscriber }

The bundle's configuration is siteaccess aware. This is an example of settings (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"]

These are your YooChoose customer ID and license keys.

The URI your site's REST API can be accessed from.

This allows you to define content types on which tracking script will be shown. Go to the Tracking section to get more details.

If content's author or image are stored in different field, you can specify it in parameters.yml

    ez_recommendation.field_identifiers:
        {field fetched by controller (image or author)}
             {content type}: {field with value}

For example:

    ez_recommendation.field_identifiers:
         author:
             article: authors
         image:
             article: thumbnail
             blog_post: main_image

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'

All of those settings will set advanced options for YooChoose backend. Changing any of these parameters without a valid reason will break all calls 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. This 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 server's REST API will need to be open to the YooChoose servers for indexing to be possible.

Events from the site needs to be sent to YooChoose so that recommendations can be adapted to visitors. Tracking can be setup in multiple ways, depending on anyone's constraints.

EzRecommendationBundle delivers Twig extension which helps integrate tracking functionality into your site. All you need to do is place small snippet code somewhere in the HEAD section of your header template (if your bundle is built on top of the DemoBundle this is page_head.html.twig):

{% if content is defined %}
    {{ yc_track_user(content.id) }}
{% endif %}

Next step is to configure settings under the recommender.included_content_types parameter (see: default_settings.yml file delivered with this bundle).

Here you can define for which content types tracking script will be shown.

You can find more information on the YooChoose documentation, about tracking in general, and about the generic asynchronous javascript tracker.

Additionaly, in case of missing content owner Id, there's option in default_settings.yml to set up default content author:

    ez_recommendation.default.author_id: 14   # ID: 14 is default ID of admin user

###Displaying

In order to allow displaying recommendations on your site you must add portions of scripts which will integrate recommender engine with your site.

Implementation is very easy and can be performed in just a few steps (assuming that EzRecommendationBundle is properly configured and enabled in EzPublishKernel.php):

• add additional JavaScript assets to your header template (if your bundle is built on top of the DemoBundle this is page_head_script.html.twig):

{% javascripts
    ...

    '%kernel.root_dir%/../vendor/components/handlebars.js/handlebars.min.js'
    '@EzSystemsRecommendationBundle/Resources/public/js/recommendationtemplaterenderer.js'
    '@EzSystemsRecommendationBundle/Resources/public/js/recommendationtemplatehelper.js'
    '@EzSystemsRecommendationBundle/Resources/public/js/recommendationrestclient.js'
%}

• place dedicated Twig helper in place where you want to display recommendations (see further below for example):

{{ yc_show_recommendations(
    contentId = content.id,
    scenario = '',
    limit = '',
    contentType = '',
    template = '',
    fields = []
) }}

Parameter meanings (all bellow are required):

Sample integration should look like below:

{{ yc_show_recommendations(
    contentId = content.id,
    scenario = 'popular',
    limit = 5,
    contentType = 'article',
    template = 'default',
    fields = ['ez_publishedDate', 'ez_url', 'title', 'image', 'author', 'intro']
) }}

You can also bypass named arguments using standard value passing as arguments.

The ItemId mentioned throughout this documentation is usually set to the viewed ContentId. Depending on requirements, it can be set to a different value, in collaboration with YooChoose.

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:

monolog:
    handlers:
        ez_recommendation:
            type:   stream
            path:   "%kernel.logs_dir%/%kernel.environment%.recommendation.log"
            channels: [ez_recommendation]
            level: info

You can replace info by debug for more verbosity.