Inspire API

General

epoq Inspire generates relevant recommendations that provide inspiration for the online shop. To this end, the click and purchase behavior of every shop visitor is recorded in a knowledge base and processed into a history. Using a self-learning technology, the shop visitor is presented with product or content recommendations that match the interest.

  1. For the setup of the Recommendation Engine we need your product catalog in XML or CSV format.
  2. We provide you with the tracking code for the connection to our knowledge base, which you integrate into your online shop.
  3. You will receive a code snippet as a placeholder for the front end of the relevant recommendations, which you integrate into your online shop. It does not matter which shop system you work with. The Inspire widgets can be integrated on different pages of your shop.
  4. The relevant recommendations are checked in detail in the test system and different strategies are set up in consultation with you.
  5. After a short learning phase, the relevant recommendations are personalized and activated in the online shop after your approval.

The relevant recommendations can not only be played out in the online shop, but also in print elements and emails.

 

Technical Integration

For API integration, you will find all the necessary information on this page to integrate epoq Inspire into your online shop.

 

Parameters for retrieving recommendations (getRecommendations)

Required REST-API /JSON Description
x productId Clear identification of the product.
x tenantId The unique identification of your online shop (will be assigned to you by us).
x sessionId

A unique identifier of a customer's session in the online shop.

The session ID is automatically generated from the epoq JavaScript and placed in the epoq cookie "eqsid_". With the REST API, care must be taken that the session ID is taken from the epoq cookie.The session ID should only be set explicitly in special cases in consultation with us.

Important note: If there is no value in the cookie, an eqsid_ session cookie must be set. Please use the following format "_SESSIONID" (underscore in front of the session ID). The session ID must be a long enough number, we recommend the UUID.

Example: _ea8503ea-e9bd-11e4-b02c-1681e6b88ec1

optional

Do not use in production mode!

demo To test the layout, random recommendations can be requested herewith.This works only when the catalog is loaded.
x widgetTheme There are several types of widgets.
optional locakey

If it is a multilingual online shop, a 'key' must be passed here for the language in which the page is currently displayed. If this is passed in the catalog, it must also be passed when the page is called up.

Example: epoq_locakey = 'en';

x rules Rules can be passed here, such as cartlayer.Please always specify a widget ID.If you want to set special rules, we will help you with the configuration.

 

Display of recommendations - getRecommendations

Recommendations are displayed at the point in the online shop (e.g., a certain shop page) where the getRecommendations query is embedded and where handling of the response data is done.

Recommendations can be picked up for:

A single product

Recommendations can be displayed under the product on its product detail page. 

The visitor's current shopping cart

Recommendations can be displayed to the visitor in their shopping cart. 

Personal recommendations (A customer based on their entire customer history.)

These can be displayed, for example, on the customer's welcome page or on the page the customer is shown after logging in.

Cookie recommendations (A customer based on their click and purchase history from the stored cookie.)

These can be displayed on the homepage of the shop, for example. This cannot be done from the backend and should be implemented via AJAX/JSON.

Multiple widgets at the same time (getRecommendations()?rules=RULE1;RULE2)

It is important to sent only one getRecommendations call when displaying multiple widgets on the same page. A common mistake is to send two getRecommendations calls for the same page.

Only if we receive one request per page, we can ensure that multiple widgets on a page are duplicate-free.

 

Retrieving of recommendations

The recommendations are requested from us using the getRecommendations() function and the corresponding widget ID as parameters.

You can see the parameters in detail above Parameters for retrieving recommendations.

 

REST-API

The call getRecommendations() should be built into the template. The following call parameters are required:

  • tenantId: "YOUR_EPOQ_IDENTIFICATOR",
  • sessionId: "SESSION_ID",
  • rules: "WIDGET_ID1;WIDGET_ID2",
  • productId: "PRODUCT_ID",
  • demo: 6, (for test purposes only!)
  • widgetTheme

The session ID is automatically generated from the epoq JavaScript and placed in the epoq cookie "eqsid_". When using REST API, please take care that the session ID is taken from the epoq cookie.

By default, the following fields are returned per recommendation:
"@no" Number of the recommendation (0 to ..)
"@id" ProductId
"@name" Product name
"@link" Product url
"@image_link" Link of the product image (small_Image)
"@price" Price (with two decimal places)
"@feedbackurl" Feedback url

You can also query additional fields with this method. The prerequisite is that these fields exist in the catalog and are available to us. For this the parameter "&fields=FELDNAME1,FELDNAME2" must be passed. Additional fields must be released by us. In this case please let us know which fields you need.

Shopping cart

For recommendations for the shopping cart page it is very important that the updateCart() function is sent before the getRecommendations call, otherwise we do not have the information about the contents of the shopping cart. 

Homepage

On the start page there are different types of recommendations you can display. We distinguish here between recommendations based on the complete customer behavior and personal recommendations based on the individual behavior of a single online shop visitor.

Recommendations based on the complete click and purchase behavior usually deliver top sellers. To display personal recommendations, you can choose between two methods:

  1. Recommendations based on customer number.
  2. Recommendations based on cookie-based information.

To be able to display personal recommendations, the customer number must also be transferred. This can usually only be done if the online shop visitor has actually authenticated himself in the shop. This probably covers only a small part of the online shop visitors.

For this reason, there is the possibility to save the profile of a customer in a cookie. The cookie is stored under the subdomain <tenantId>.arc.epoq.de with the name eqc_eqe. The content of the cookie must be passed as a parameter at the latest when fetching the recommendations via the getRecommendations() method.

Please implement the getRecommendations call on the homepage in JavaScript. If you use the rest interface in the shopping cart, please add a tracking pixel there.

Recommendation format

The widgetTheme parameter defines in which format the recommendations should be returned. Here is a short overview of the different possibilities:

  • Slim XML (product IDs only).

  • Extended format with additional attributes from the catalog (JSON or XML)

 

"widgetTheme=multixml" returns the recommendations in XML format. Multiple "domains" can be requested. Each one represents one rule.

"widgetTheme=json2" returns the recommendations in JSONP format.

"widgetTheme=xml2" returns extended attributes in XML format.

Sample XML with product ID only

<?xml version='1.0' encoding='ISO-8859-1' standalone='yes'?> <recommendations xmlns='https://epoq.de'>

  <domain no='0' rules='WIDGET_ID'>

 <recommendationId>7aa7876d-b306-4fcc-8c82-1d8e8f60be92</recommendationId>

 <recommendation>

  <productId>REC_PRODUCT_ID1</productId>

 <url><![CDATA[https://rs1.epoq.de/inbound-servletapi/click?tenantId=YOUR_EPOQ_IDENTIFICATOR

 &sessionId=SESSION_ID&recommendationId=7aa7876d-b306-4fcc

 -8c82-1d8e8f60be92&productId=REC_PRODUCT_ID1]]></url>

 </recommendation>

 <recommendation>

  <productId>REC_PRODUCT_ID2</productId>

 <url><![CDATA[https://rs1.epoq.de/inbound-servletapi/click?tenantId=YOUR_EPOQ_IDENTIFICATOR

 &sessionId=SESSION_ID&recommendationId=7aa7876d-b306-4fcc

 -8c82-1d8e8f60be92&productId=REC_PRODUCT_ID2]]></url>

 </recommendation>

</domain>

<domain no='1' rules='xyz'>

<recommendationId>123435-b306-4fcc-345435-344552g</recommendationId>

 <recommendation>

  <productId>REC_PRODUCT_ID1_A</productId>

 <url><![CDATA[https://rs1.epoq.de/inbound-servletapi/click?tenantId=YOUR_EPOQ_IDENTIFICATOR

 &sessionId=SESSION_ID&recommendationId=123435-b306-4fcc-345435

 -344552g&productId=REC_PRODUCT_ID1_A]]></url>

 </recommendation>

 <recommendation>

 <productId>REC_PRODUCT_ID2_B</productId>

 <url><![CDATA[https://rs1.epoq.de/inbound-servletapi/click?tenantId=YOUR_EPOQ_IDENTIFICATOR

 &sessionId=SESSION_ID&recommendationId=123435-b306-4fcc-345435

 -344552g&productId=REC_PRODUCT_ID2_B]]></url>

  </recommendation>

 </domain>

 </recommendations>

 

Sample XML2 with additional attributes

<?xml version="1.0" encoding="UTF-8"?>

<recommendations xmlns="https://epoq.de" xmlns:g="http://base.google.com/ns/1.0" xmlns:e="http://base.google.com/cns/1.0" xmlns:c="http://base.google.com/cns/1.0">

<domain xmlns="" no="0" rules="rule1,rule2">

<recommendationId>076b7fa9-11ed-4cad-a8a4-8dac4884d4f8</recommendationId>

<items xmlns="https://epoq.de">

<item xmlns="" no="0" g:id="303381001" g:name="KHUJO Tamarind lightpink" g:link="http://www.fshop.com/KHUJO-Tamarind-lightpink/303381001/" image_link="http://www.shop.com/gateTools/scripts/binary.php?BinaryCodeID=973735&amp;NoRefCheck=1" g:price="69.95" feedbackurl="https://rs1.epoq.de/inbound-servletapi/click?tenantId=shop&amp;sessionId=manakin*699475591&amp;recommendationId=076b7fa9-11ed-4cad-a8a4-8dac4884d4f8&amp;productId=303381001&amp;target=http%3A%2F%2Fwww.shop.com%2FKHUJO-shop-lightpink%2F303381001%2F" />

<item xmlns="" no="1" g:id="299665001" g:name="INSIGHT Summer Rose Dress white-multicolored" g:link="http://www.shop.com/INSIGHT-Summer-Rose-Dress-white-multicolored/299665001/" g:image_link="http://www.shop.com/gateTools/scripts/binary.php?BinaryCodeID=989384&amp;NoRefCheck=1" g:price="79.95" feedbackurl="https://rs1.epoq.de/inbound-servletapi/click?tenantId=shop&amp;sessionId=manakin*699475591&amp;recommendationId=076b7fa9-11ed-4cad-a8a4-8dac4884d4f8&amp;productId=299665001&amp;target=http%3A%2F%2Fwww.shop.com%2FINSIGHT-shop-Rose-Dress-white-multicolored%2F299665001%2F" />

</items>

</domain>

</recommendations>

 

Sample JSON with additional attributes

jQuery16109371099133865392_1336036472034({"recommendations": {"domain": { 

"@no": "0",

"@rules": "VariationFilter",

"recommendationId": {"$": "82810ebe-be72-4fb4-a289-48cabab9dbea"},

"items": {"item": [

{

"@no": "0",

"@id": "123176-25",

"@name": "Damen T-Shirt",

"@link": "http:\/\/meinshop.de\/damen\/bekleidung\/shirts-und-tops\/public-damen-t-shirt--7111\/",

"@image_link": "http:\/\/meinshop.de\/images\/product_images\/211.164x164.jpg",

"@price": "",

"@feedbackurl": "https:\/\/rs1.epoq.de\/inbound-servletapi\/click?tenantId=YOUR_EPOQ_IDENTIFICATOR&sessionId=SESSION_ID

&recommendationId=82810ebe-be72-4fb4-a289-48cabab9dbea&productId=123176-25

&target=http%3A%2F%2Fmeinshop.de%2Fdamen%2Fbekleidung%2Fshirts-und-tops%2Fpublic-damen-t-shirt--71111"

},

{

"@no": "1",

"@id": "113334-15",

...

]}

}}}) ;

 

Click feedback of the recommendations

In order for epoq Inspire to learn which recommendations are clicked, the information must be transmitted to epoq. There are three ways to do this:

Option 1: You can use the URL that is in the <feedbackurl> or <url> field of the response (see examples above). This URL can be called either from the backend or from the client side.

Option 2: Use as parameter "eqrecqid" in the URL (with the entry from the <recommendationId> field from the recommendation, see above examples): http://www.URL.PRODUCTDETAILPAGE?eqrecqid=154c337f-6d20-464b-8ccb-6f863e8332c6

 

Displaying recommendations in print elements

You can display the recommendations on your homepage or in emails, as well as in print elements. For example, package inserts that are attached to the package with the delivery bill.

The technical requirements are 

  • the integration of epoq tracking

  • a printer that can be used to create the print elements and 

  • an interface that we can use to provide you with the appropriate recommendations. This interface will be created individually in consultation with you.

 

Tips

Recommendations based on customer data / cookie

Here we recommend integrating the viewItem() call (view of a product) via the web API. Likewise, the recommendations should be fetched via JavaScript. If the calls are generally sent from the backend (REST API), a cookie pixel must be passed when calling the processCart() function so that epoq can read the data from the cookie.

You can find more information in the article Tracking.

 

Installation of the recommendations

In general, we recommend sending the getRecommendations() call from the backend (REST API). If a caching system is in use, or the recommendations are fetched in JSON format to be displayed via AJAX, the calls are sent from the frontend.

An exception to this is fetching the recommendations on the homepage. This should be done in JavaScript to ensure the cookie is transferred. Parsing and rendering the response can then be done in JavaScript or via AJAX in the backend. 

 

AJAX

Currently, the click feedback is automatically integrated when the viewItem call is integrated via JavaScript and our script is used to display the recommendations.

 

Details

Caching

In general, individualization (personal recommendations) and caching do not go together because the purpose of both things is quite different. Cached recommendations are usually no longer individual. The use of a caching system usually does not allow to assign a unique and performing session ID per online shop visitor.

If a caching system is in use, the AJAX/JSON variant of the integration should be selected.

 

SEO / duplicate Content

The integration of epoq Inspire can also have effects on SEO (Search Engine Optimization). To avoid unwanted side effects, such as "duplicate content" (the content of the page can be accessible via multiple URLs), we recommend that you add the parameter which sets the authoritative URL of the product and can be read by Google & Co:

duplicate Content
< link rel="canonical" href="http://www.example.com/product.php?item=swedish-fish" / > 

 

Timeout strategy

Since our service, as well as all other hosted services, can occasionally experience delays in response time simply due to the connection via the public network, we strongly recommend taking precautions to avoid any additional downtime risk for the online shop.

Therefore, timeouts should always be set for all calls to epoq Inspire. These ensure that if a certain response time is exceeded, the service will no longer wait for a response and the page will be built without the information expected by the service.

The length of the timeouts should be between 500 milliseconds and 2.4 seconds, depending on the request. Normally, our service answers all requests in less than 100 milliseconds.

 

Filters / Rules

epoq Inspire provides numerous recommendations that reflect the personal buying behavior of customers in the shop. In many cases, it makes sense to adapt the variety of recommendations to the recommendation point in the shop. For this purpose, we can shop rules for you that filter or, in some cases, extend the recommendations.

Rules can filter recommendations as well as change the behavior of the service. These are configurable in two places:

  • As an additional or modified parameter when requesting a recommendation. For this the parameter "&rules=WIDGET_ID" must be passed (e.g. rules=entryPage).
  • As a fixed configuration for your shop. We will set this up for you on request.

As far as the rules are filters, they can be combined as you like. Each filter restricts recommendations further. If a rule is an extension (e.g. adding manual recommendations) there may be certain restrictions if you want to use a filter for this. Please contact us and let us know your ideas.

Was this article helpful?

/