Child pages
  • OXID Connect - Module Tutorial (DEPRECATED)
Skip to end of metadata
Go to start of metadata


Your customers expect high quality recommendations. They want to be supported in their purchasing decision and selection process. By using Yoochoose recommendations you increase the usability and the level of professionalism in your online shop. The recommendations present products to the customer he did not anyhow expect to find - in contrast to search.

If you are not familiar with the usage of recommendations, please read at least the two first pages of the Yoochoose User Guide [1]. Otherwise you can proceed with the following steps.

Getting Started


OXID eShop version

  • CE 4.7.x - 4.8.x or
  • EE, PE 5.0 4.7.x/5.0.x - 4.8.x/5.1.x


First of all the Yoochoose module package must be downloaded from the OXID eXchange [3] website (search for "yoochoose").

The installation itself includes three steps.

  1. Execute the SQL script using the /Service/Tool menu of the OXID admin backend.
  2. Copy the module code into the modules folder of the OXID installation. The folder modules must get a new subfolder Mediaopt.
  3. Insert the PHP code from the install.txt into the file /modules/functions.php

oxid module installation

Firewall Configuration

OXID Recommendation module needs permanent connection to the Yoochoose recommendation engine. There are three servers:

  • Event tracking:
  • Recommendation controller:
  • Configuration server (used only in the admin backend):

Both http (port 80) and https (port 443) ports must be open for outbound TCP connections. One must not build the firewall rule based on IP. The Yoochoose infrastructure is located in the AWS cloud and the IP addresses can be changed.

OXID Firewall

The OXID recommendation module loads recommendations using JavaScript after the shop page is already rendered. If the Yoochoose infrastructure is not available, it won't affect the loading time of OXID webpages.

The OXID recommendation module does not provide recommendation caching internally, but the recommendation controller does support modification end expiration headers. Therefore one can configure a local caching proxy for recommendation results. More information to recommendation caching can be found in the Developer Guide [2], chapter Fetching Recommendations.


Account Registration

Before the recommendation engine can be enabled for your web shop, one must register a new OXID Connect account on the Yoochoose web page.

An account contains a default scenario configuration for an average web shop. If you are configuring a highly visited web shop (over a million page requests per month), it makes sense to ask for the special consulting and phone support by Yoochoose GmbH.

Module Activation

After a new Yoochoose account is created, you need to transfer the credentials from the Yoochoose dashboard

to the OXID back-end


Yoochoose customer ID and license key must be first entered into the plug-in configuration. Then the plugin must be activated. 


Please be patient. After the plugin is activated it takes about a day, until the first recommendations are available. The recommendation engine needs to collect statistic information before high quality recommendation can be provided. After the information is available, the recommendation will be shown automatically. If you are not sure about the quality of the recommendation, you can disable recommendation boxes for several days until the engine collected enough information and enable it manually for a test.

Structure and Functionality

The recommendation module is configured with 5 recommendation boxes throughout the OXID shop:

  • Landing-Page recommendations with most popular products
  • Category-Page recommendations with the most popular products in the selected category
  • Product Detail Page 1 recommendations with the products that were bought with the currently displayed product
  • Product Detail Page 2 recommendations with the alternative products that were bought together or instead of the displayed product
  • Checkout recommendation with the products that are bought with the products from the shopping cart.

oxid screens

Basic configuration can be also done in the OXID admin backend. There you can select the recommendation engine scenario for every recommendation box, specify the amount of recommended products for every box, or disable single boxes.

oxid enable-disable

Extended configuration of recommendation scenarios (for example enabling of personalized recommendations) can be done in the Yoochoose Configuration Backend [4]. For more information about different scenarios and configuration options see the User Guide [1]. 

Replacing Recommendation Box Title

If you reconfigure several or all the recommendation scenarios, it is useful to rename the default titles of the recommendation boxes to state the purpose of the recommendations. For example rename "Customers Who Bought This Item Also Bought" into "Our special selection personally for you". Texts can be changed using the standard OXID feature in

/Customer Info/CMS Pages/Search for "yoochoose"

Disabling Embedded Recommendation

Several cross selling boxes are available in OXID out of the box. In most cases it makes sense to deactivate the ones, which are duplicated by the Yoochoose recommendations. It can be done in the OXID admin backend in

/Master Settings/Core Settings/Performance/Enhanced Performance Settings


Submodels belong to the extended configurations. Please check, if you will get advantages from using it. See the User Guide for more information or ask for consulting.

The OXID recommendation module allows to provide a single attribute during the recommendation request. It must be the same attribute the submodel is configured for.

In order to use submodels, please check that the submodel usage is activated and configured in

  • the OXID admin backend

  • the Recommendation Scenario configuration

  • the Recommendation Model configuration

OXID Submodels

Enabling Search

Enabling the search in OXID is done by including some .js files in the header section of the OXID theme's base.tpl. 


Including the search
	<script type="text/javascript" src=""></script>
	<script type="text/javascript" src=""></script>
	<script type="text/javascript" src=""></script>
	<script type="text/javascript" src="//<your-customer-id>/tracking.js"></script>
	<link rel="stylesheet" type="text/css" href="//<your-customer-id>/tracking.css" />

Please make sure to use the correct customer ID which you received after registering your product ...

The javascript is hooked to the #searchParam input by default. If this id has changed on your theme, please contact

After cleaning the cache, and a successful import It should look like following after relaoding the page





  1. Yoochoose Recommendation Engine User Guide
  2. Yoochoose Recommendation Engine Developer Guide
  3. OXID eXchange. Marketplace for OXID eShop extensions
  4. Yoochoose Configuration Backend



  • No labels