Child pages
  • eZ Personalization Solution
Skip to end of metadata
Go to start of metadata

Please see https://doc.ez.no/display/EZSERVICES/eZ+Recommendation+Bundle for the current documentation

The documentation here is only due to legacy availability

 

Introduction

The eZ Personalization Solution is a completely client-based recommendation extension that can be integrated into eZ Publish. It includes a tracking mechanism that sends usage data to the recommender tracking servers to calculate recommendations.

It can be used for

  • displaying personalized recommendations that meet his interest based on a users's behavior
  • providing recommendations based on the current context of a user (the content itself)
  • push defined content (e.g. paid and non-paid)
  • cross-recommend content (e.g. users who read this article also watched this video)
  • provide information about the current content (e.g. how many users are currently watching the content that recommendations are requested for)
  • provide search suggestions and matching content

Requirements

In order to enable the extension, some preparation is needed which covers the following

  1. Install the bundle -> https://github.com/ezsystems/EzSystemsRecommendationBundle
  2. Register an account (a so-called mandator) via support@yoochoose.com
  3. Allow access to the eZ instance's API 
  4. Define what should be tracked and enable the tracking -> https://github.com/ezsystems/EzSystemsRecommendationBundle#tracking-of-users-activity
  5. Define the content to be imported
  6. Style and enable the rendering of recommendations ->  https://github.com/ezsystems/EzSystemsRecommendationBundle#displaying

That's it.

Whitelisting to access the eZ API

YC needs to access the API of an eZ installation in order to sync customer data. If a whitelist of IPs is needed, use the following ones

  • 46.51.203.199
  • 46.51.199.127
  • 87.139.123.237
  • 92.50.96.242
  • 46.137.101.208
  • 54.229.102.177
  • 79.125.126.82
  • 54.93.91.48
  • 54.93.179.211
  • 52.215.22.234
  • 54.77.201.13

Content types to be tracked

Define the list of content types, their identifier and the language that should be tracked and recommended. You can only recommend what you are tracking.

content typeidentifierlanguage
16articleeng-GB
72blogeng-GB
...  

Send a complete list to support@yoochoose.com or contact YOOCHOOSE employees directly.

Import of customer data

Import operations could cause heavy load on the customer's server if the wrong params regarding pages and page_size are provided. Please test locally if the server can stand this load. Iterate over all the content that should be exported and if this works fine, start the initial import.

All actions related to importing data requires BASIC AUTH based on your customer ID and license-key information (available under https://admin.yoochoose.net).

You can verify the import controller of the bundle by calling the local API. To check if content interface is working as expected, please check this URI

GET http://{endpoint}/api/ezp/v2/ez_recommendation/v1/content/{contentId}?lang={language}&fields={csvlist_of_content_fields}&page=1&page_size=5

Accept    application/vnd.ez.api.Content+json
Authorization    Basic xxxxxxxx

 

To check if the contenttype interface is working and delivers the correct content fields:

GET http://{endpoint}/api/ezp/v2/ez_recommendation/v1/contenttypes/16?lang={language}&fields={csvlist_of_content_fields}&page=1&page_size=5

Accept    application/vnd.ez.api.Content+json
Authorization    Basic xxxxxxxx


By default the following fields of eZ Content are imported:

  • uri
  • identifier
  • language
  • publishedDate
  • categorypath (content object structure that leads from the root content to the current)

All additional data that should be delivered from the Recommendation Service to be rendered on the client-side must be configured. For examples see the table below

content typeidentifierlanguageadditional fields to be imported
16articleeng-GBshort_description, title, image
72blogeng-GBabstract, title
...   

In case of an image, only the hyperlink is stored in the Recommender.

Send this list to YC and we will take care of the setup process.

Initial full import

It is required to make an initial import of customer data to fill the Recommender System with the data that should be delivered with a recommendation response. There is a "notification" interface on the Recommender System that triggers a full import. It can be accessed by a POST request with the following body information.

 

POST https://admin.yoochoose.net/api/v4/publisher/ez/<mandator>/notification

 

Full import notification
{
	"transaction" : null, //optional
	"events" : [
		{
		 	"action" : "FULL", // defines that an initial full import is triggered
        	"uri" : null, // is derived from the mandator settings in the registration process
        	"contentTypeId" :16,
        	"lang" : "eng-US", // see definitions above
        	"pages" : 1,			// 20 content objects should be fetched within 1 page
        	"pageSize": 20, 			// the pageoffset where to start paging. 10 causes to start with page 11 and fetch "pages" (here: 1) more pages with a page_size of "pageSize"
        	"offset": 10 			// optional!! the API call would result in http://ez.publish.installation/api/ezp/v2/ez_recommendation/v1/contenttypes/16?lang=eng-US&fields=title,image,short_description&page=11&page_size=20
		}
	]
} 

Incremental import

The eZ backend sends a notification automatically to the Recommender System when content was deleted or updated. With this mechanism the content of the Recommender Engine stays in sync with the customer content.

The notification URL stays the same, just the body changes:

{
	"transaction" : null, //optional
	"events" : [
		{
		 	"action" : "UPDATE",
        	"uri": "/api/ezp/v2/content/objects/123456"
		}
	]
} 

The recommender will then later fetch this content via the API of the customer system and update the local data which can be returned in a recommendation response.

Fetching Recommendations

Fetching recommendations is implemented in the bundle and can be enabled in templates by following the instructions under https://github.com/ezsystems/EzSystemsRecommendationBundle#displaying 

Recommendation responses contain all requested data which is available, i.e. successfully imported. For example a request

GET http://reco.yoochoose.net/api/<mandator>/<user>/blog.json?...&attribute=uri&attribute=title&attribute=image&attribute=short_description

would deliver the following response

Recommendation response
{
  "recommendationResponseList": [
    {
      "reason": "POPULARITY_SHORT_CLICK (context: ITEM(s))",
      "relevance": 2,
      "itemType": 3,
      "type": "POPULARITY_SHORT_CLICK",
      "clickRecommended": "//event.yoochoose.net/api/<mandator>/clickrecommended/<user>/<contentType>/<contentId>?scenario=blog",
      "attributes": [
        {
          "name": "image",
          "value": "/var/ezflow_site/storage/images/media/yellow-banded-poison.jpg"
        },
        {
          "name": "short_description",
          "value": "<p>Ten diminutive, colorful dart-poison frog species are featured in a lively vivarium in the Museum’s live-animal exhibition <em>Frogs: A Chorus of Colors,</em> now open at the Museum. Get to know a few!</p> "
        },
        {
          "name": "title",
          "value": "Know Your Dart-Poison Frog "
        },
        {
          "name": "uri",
          "value": "/explore/news-blogs/123456"
        }
      ],
      "itemId": 123456
    }
  ]
}

This response can be interpreted and rendered by the RecommendationBundle's own HandleBar templates.

Recommendation response V2

You can also use the extended version of a recommendation response but this needs some adaption in the rendering templates. The advantage is, that you have by default additional information about the current context (e.g. the page you are watching) like how many users are currently looking at this content. For more information please see 2b. Fetching Recommendations V2
  • No labels