Integration Guide with default Narratives

Owned by Sylvain Paillard
Last updated: Nov 30, 2020
43 min read

Overview

This document provides the key information about how to set-up a standard integration of the first line of Boxalino Widget & Page Optimizers (WPOs) : Welcome, Search, Up-Sell, Cross-Sell & Re-buy.

These WPOs are the typical WPOs to start with a correspond to the level 1 of the WPO matrix:

In this document, we discuss a typical API integration which can be done in any programming language in any e-shop system (if you use Shopware or Magento, please contact Boxalino for the specific material for these e-shops).

Boxalino Narrative API - key concept: LAYOUT

Boxalino Narrative API returns dynamic layout content to be displayed in your e-shop. This means that you will receive directly the layout which should be implemented for the specific situation you are in.

The full technical details of the JSON request and response formats and structure is described in the document : “Narrative API - Technical Reference”.

Let’s take the example of search, by default, Boxalino returns 3 different layout depending on the search situation:

  1. Normal search results (with or without auto-correction)

  2. Sub-phrases results (with several groups of results each matching a sub-part of the search query)

  3. No results (with a block of personalized recommendations to avoid showing a fully empty page)

Layout diagrams of case 1, 2 and 3

This mean that the logic of which layout should be applied in which case is configured in Boxalino. What the Narrative API returns is the layout which should be applied in the current situation.

This reduced considerably the amount of business logic which should be programmed in your controller and makes changes much easier as it’s only about configuration changes in the Boxalino Intelligence Admin.

The detailed default layout with each templates of search is described in detailed in the Search section below.

Boxalino Narrative LAYOUT Structure

The layout structure of Boxalino consists in a list of blocks and each blocks can have children blocks.

Example of layout response of Boxalino Narrative API (simplified):

{ "blocks": [ { "template":"title", "title":"Your Search results for 'a search'", "blocks": [] }, { "template":"product-list", "blocks": [ { "template": "product", "bx-hit": { "id": "155524", "groupValue": "155524", "score": 88.96804809570312, "title": "The title of the product", "discountedPrice": 19.9, "products_brand": [ "Könitz" ] } "blocks": [] } ] } ] }

In a simple way, you can map the main blocks as your “rows” and their children as your “cols” if you follow a typical Responsive framework like Bootstrap.

In case of a column layout (e.g.: search filters on the left), a parameter “position” is provided with a target container value (e.g.: “left”) in some of the first level blocks. You can then simply take the list of main blocks with different position to integrate the Narrative blocks to the different containers of your page (the left position will be exemplified in the examples about the Search WPO below).

The complete request and response JSON structure are fully described in the document : “Narrative API - Technical Reference”.

Key steps to integrate Boxalino Narrative API

Step 1 : Prepare a Narrative Request & Layout Micro-service connector

First, you need to prepare a Micro-service connector which will make the calls to Boxalino Narrative API and dispatch the returned layout to your front-end views (templates).

Key things to consider for your Micro-service connector:

  1. Make sure it is easy to parametrize the key parameters for multiple cases, mainly:

    1. widget (name of the WPO instance : search, navigation, product recos, …)

    2. language (de, fr, en, …)

    3. hitCounts (how many products should be returned in the layout)

    4. offset / sort / selected facets (for search and navigation)

  2. Pass the correct sessionId and profileId in your request (the sessionId and the profileId should match the value of the cems and cemv cookies which are automatically set by our tracker, if they are not set yet, you need to create them (unique strings) and save them in the cookies)

  3. Pass the profileId also as a URL parameter to the endPoint (see Test your request to Boxalino Narrative API below)

  4. Create a connection pool with Curl (to avoid recreating the connection every time)

  5. Implement an automatic fall-back on the fall-back domain in case the main service is not responsive

  6. If some data cannot be returned directly from Boxalino (e.g.: current price might be not yet up-to-date in our index), implement a way to loop through the response blocks tree to detect all the instances of “bx-hit” parameter so you can load in one Database request all the prices needed for the display of the page, you can then simply add them to the JSON or provide them as an resource in the models of your templates

Step 2 : Prepare your Templates

Depending on which WPO you will implement you will need to prepare different templates.

Each template must be able to be rendered on the basis of the defined template parameters.

Step 3 : Implement / Integrate your URL routing logic

Your template will display a certain amount of links for:

  • add / modify a facets (search / navigation filter)

  • change the sort order

  • go to a search result page on a specific query

  • …

Make sure that you implement these URL in a way which if possible already matching the URL routing logic you have in your e-shops or in a way which is easy to extend on the basis that you have.

Step 4: Test, Adjust & Go-Live

When your Micro-Service connector is done, your templates are ready and all your URLs are supported, then it is time to test, adjust and go-live.

Test your request to Boxalino Narrative API

The End-point is always structured as follows:

POST https://[SUB-DOMAIN].bx-cloud.com/narrative/[ACCOUNT]/[PATH]/[VERSION]?profileId=[PROFILE_ID]

with:

SUB-DOMAIN: the Boxalino Real-Time Cloud (RTC)

  • “main” for production (do not use for dev / stage)

  • “r-st” for dev / stage

  • “ch” for Swiss Data Center Fall-Back (will be available soon)

  • “track” for tracker and batch requests

ACCOUNT: your account name

PATH: a configurable path for your narrative, typically “standard”

VERSION: the version number of your end-point configuration (1 if you don’t use versioning)

PROFILE_ID: the same value as what you provide in the base parameters described below (content of the _cemv cookie), for batch request, take the first customerId of the list

Above : Example query with ARC (Advanced Rest Client) Chrome extension

https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo/related

Before testing your integration with code, we recommend you to test it with this extension to make sure it technically work.

WELCOME & RE-BUY (product recos on start / account pages)

Download standardized Narratives:

Layout & Templates

As all standard product recommendations, the layout of the Welcome & Re-Buy is based on a product-slider template which displays, as children blocks, product templates.

Sample request

{ "username": "your-acccount", "apiKey": "your-api-key", "apiSecret": "your-api-secret", "sessionId": "3b1c931d.68973202.161.17067d62c2b", "profileId": "123456", "customerId": "5555", "widget": "home", "dev": false, "test": true, "hitCount": "40", "language": "de", "groupBy": "products_group_id", "returnFields": [ "title", "discountedPrice" ], "parameters": { "User-Host": "62.2.185.11", "User-Referer": "https://www.google.ch", "User-URL": "https://www.yourwebsite.ch", "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36", "bx_debug_level": "0" } }

Sample Response

{ "blocks": [ { "template": [ "product-slider" ], "magento_block_type": [ "product-slider" ], "bx-hits": [ "accessor" ], "title": [ "Ihre persöhnliche Empfehlungen" ], "see_all_label": [ "" ], "see_all_link": [ "" ], "accessor": [ "" ], "blocks": [ { "template": [ "product" ], "model": [ "product" ], "bx-hit": { "score": 48.67390823364258, "discountedPrice": 250, "id": "59894", "title": "Grillplausch auf dem Bodensee 1 Stunde (10 Personen)" }, "accessor": "accessor", "blocks": [], "index": 0 }, { "template": [ "product" ], "model": [ "product" ], "bx-hit": { "score": 48.67390823364258, "discountedPrice": 280, "id": "59797", "title": "Romantik Spa im Thermalbad Zurzach" }, "accessor": "accessor", "blocks": [], "index": 1 }, { "template": [ "product" ], "model": [ "product" ], "bx-hit": { "score": 48.67390823364258, "discountedPrice": 350, "id": "59895", "title": "Grillplausch auf dem Bodensee 2 Stunden (10 Personen)" }, "accessor": "accessor", "blocks": [], "index": 2 } ] } ] }

SEARCH

Download standardized Narratives:

Layout & Templates

Search comes into 3 different layouts:

Standard layout (with results)

The standard layout of search results returns first a block of the template facet-list with position:left.

Then, for the main part, returns

  • a block with the title template

  • a block with the product-list-bar template

    • children block with the pagination template

  • a block with the product-list template

    • children block with the product template

  • a block with the pagination template

Sub-phrases layout (no results for all searched words, but for sub-parts)

The sub-phrases results returns first a block of the template title.

Then, follows a dynamic list of 1 to N (typically, maximum 3-4) blocks of the template product-list each of them with, as children block, a list of blocks with the product template.

Unlike the normal search result, typically the product list are provided with values for the title and see all link. It is recommended to use the same template and simply to detect if there parameters are set to display them. The see all link will direct the user to the full search result page of this sub-phrase.

No results (but some recommendations)

The no results layout starts with a block of the template title followed by a block of the template product-slider which contains as children blocks a list of blocks of the template product.

Sample request (for search)

Sample Response (for standard layout)

Sample Response (for sub-phrases layout)

Sample Response (for no results layout)

SEARCH-AUTOCOMPLETE

Layout & Templates

The Autocomplete layout is based on two main blocks:

  • the block containing the textual suggestions list which is done with the template autocomplete-text-list, of which the children are blocks of the template autocomplete-text

  • the block containing the product suggestions list which is done with the template autocomplete-product-list, of which the children are blocks of the template autocomplete-product

 

 

 

Optionally, the autocomplete-text block can contains two children blocks:

  • a block of the template facet-list which indicates the key facets (e.g.: categories) of the textual suggestions, can be displayed (see first screen-shot below)

  • a block of the template autocomplete-product-list, of which the children are blocks of the template autocomplete-product to display products matching the search suggestion after a mouse-over.

In this example you can see in the first screen-shot how the facets can be used to suggest “in “ categories for the first textual suggestion. In the second screen-shot you can see that a mouse-over changes the products which are displayed below the textual suggestions.

Sample request

Except the widget being different (autocomplete instead of search), the only difference with the search request is the parameter acQueriesHitCount which is used to automatically detect it is an autocompelte query and not a normal search query.

Sample Response

UP-SELL & CROSS-SELL (products recos on PDP and basket)

Download standardized Narratives:

Layout & Templates

As all standard product recommendations, the layout of the Welcome is based on a product-slider template which displays, as children blocks, product templates.

Sample request

The only difference with WELCOME is the “items” parameter which should indicate:

  • UP-SELL: the current product of the PDP page

  • BASKET: the current content of the basket of the user

Sample Response

TEMPLATES

Here is the list of all the templates which are referenced in the document.

We provide every-time the default JSON-SCHEME which will define what parameters can be set in the configuration of the narratives.

All localized configuration must be defined in the different languages in the admin (default exemplified below for “fr” and “de”) but will always be returned in the JSON response in one language (the current language as set in the request.

PRODUCT / AUTOCOMPLETE-PRODUCT

Download standardized Block Layouts:

Parameter

Example Value

Description

Parameter

Example Value

Description

template

product / autocomplete-product

this template renders a specific product within a list or a grid.

Usually only two templates are required : 1 for the normal grid / slider displays of products and 1 for the search autocompletion.

model

product / autocomplete-product

models are by default provided with the same value as the template and can be changed / ignored depending on your integration needs.

bx-hit

in Admin: “accessor”

Example value in response : {
"id": "155524",
"groupValue": "155524",
"score": 88.96804809570312,
"title": "The title of the product",
"discountedPrice": 19.9,
"products_brand": [
"Könitz"
]
}

see all detailed information in the Narrative API - Technical Reference

PRODUCT-LIST / PRODUCT-SLIDER / AUTOCOMPLETE-PRODUCT-LIST

Download standardized Block Layouts:

Parameter

Example Value

Description

Parameter

Example Value

Description

template

product-list
/ product-slider
/ autocomplete-product-list

this template is a container of products (products are provided in the children “blocks”).

Usually only 3 templates are required : 1 for the normal grid, 1 for slide slider displays of products and 1 for the search autocompletion.

model

product-list
/ product-slider
/ autocomplete-product-list

models are by default provided with the same value as the template and can be changed / ignored depending on your integration needs.

title

Products you might like

the label of the container (might be ignored for product-list as usually no labels are necessary)

see_all_label

See all

the label of the see all link (might be ignored for product-list as usually no see all links are necessary)

see_all_link

product_list.html?widget=similar

the link of the see all link (might be ignored for product-list as usually no see all links are necessary)

bx-hits

accessor

must be set in the admin, but can be ignored in the response

PRODUCT-LIST-BAR

Download standardized Block Layouts:

Parameter

Example Value

Description

Parameter

Example Value

Description

template

product-list-bar

this template displays the current amount of results, as well as the sorting options and contains (as a child block) the pagination template.

model

product-list-bar

models are by default provided with the same value as the template and can be changed / ignored depending on your integration needs.

bx-sort

in Admin: “accessor”

Example value in response :
{
"field": "title",
"reverse": true
}

must be set in the admin, will contain the information about the selected sort option to be displayed (see detailed documentation in Narrative API - Technical Reference)

bx-hitCounts

in Admin: “accessor”

Example value in response :
{
"totalHitcount": 52
}

must be set in the admin, will contain the information about the total number of results (see detailed documentation in Narrative API - Technical Reference)

PAGINATION

Download standardized Block Layouts:

Parameter

Example Value

Description

Parameter

Example Value

Description

template

pagination

this template displays the current amount of results, as well as the sorting options and contains (as a child block) the pagination template.

model

pagination

models are by default provided with the same value as the template and can be changed / ignored depending on your integration needs.

bx-pagination

in Admin: “accessor”

Example value in response :
{ "totalHitCount": 22, "offset": 0, "pageSize": 10 }

must be set in the admin, will contain the information about the pagination (see detailed documentation in Narrative API - Technical Reference)

JSON SCHEME:

PRODUCT / AUTOCOMPLETE-PRODUCT

Download standardized Block Layouts:

Parameter

Example Value

Description

Parameter

Example Value

Description

template

product / autocomplete-product

this template renders a specific product within a list or a grid.

Usually only two templates are required : 1 for the normal grid / slider displays of products and 1 for the search autocompletion.

model

product / autocomplete-product

models are by default provided with the same value as the template and can be changed / ignored depending on your integration needs.

bx-hit

in Admin: “accessor”

Example value in response : {
"id": "155524",
"groupValue": "155524",
"score": 88.96804809570312,
"title": "The title of the product",
"discountedPrice": 19.9,
"products_brand": [
"Könitz"
]
}

see all detailed information in the Narrative API - Technical Reference

AUTOCOMPLETE-TEXT-LIST

Download standardized Block Layouts:

Parameter

Example Value

Description

Parameter

Example Value

Description

template

autocomplete-text-list

this template is a container of textual suggestions (textual suggestions are provided in the children “blocks”).

Usually only 3 templates are required : 1 for the normal grid, 1 for slide slider displays of products and 1 for the search autocompletion.

model

autocomplete-text-list

models are by default provided with the same value as the template and can be changed / ignored depending on your integration needs.

bx-acQueries

accessor

must be set in the admin, but can be ignored in the response

AUTOCOMPLETE-TEXT

Download standardized Block Layouts:

Parameter

Example Value

Description

Parameter

Example Value

Description

template

autocomplete-text

this template displays a auto-completion textual suggestion.

It suggested to manage also children of the templates facet-list and product-list.

with the children facet-list you can display the list of categories for the top search suggestion (e.g.: in cat A, in cat B, …)

with the product-list you can display the matching products when the user does a mouse-over the search term.

model

autocomplete-text

models are by default provided with the same value as the template and can be changed / ignored depending on your integration needs.

bx-acQuery

in Admin: “accessor”

Example value in response :
"bx-acQuery": {
"suggestion": "some term",
"highlighted": null,
"score": 36109.4609375
}

must be set in the admin, will contain the information about the textual suggestion in the response

FACET-LIST

Download standardized Block Layouts:

Parameter

Example Value

Description

Parameter

Example Value

Description

template

facet-list

this template displays a auto-completion textual suggestion.

It suggested to manage also children of the templates facet-list and product-list.

with the children facet-list you can display the list of categories for the top search suggestion (e.g.: in cat A, in cat B, …)

with the product-list you can display the matching products when the user does a mouse-over the search term.

model

facet-list

models are by default provided with the same value as the template and can be changed / ignored depending on your integration needs.

position

left

typically, the facets should be displayed in a separate left container

bx-facets

in Admin: “accessor”

Example value in response :
{
"field": "products_brand",
"url":"brand",
"label": "Brand",
"values": [
{
"value": "kuhn rikon",
"url": "kuhn-rikon",
"label": "Kuhn Rikon",
"hitCount": 3,
"selected": true,
"show":true
},
// ...
],
"position": "left",
// ...
}

 

must be set in the admin, will contain the information about the facets to be displayed (see detailed documentation in Narrative API - Technical Reference)

TITLE

Download standardized Block Layouts:

Parameter

Example Value

Description

Parameter

Example Value

Description

template

title

this template renders a specific product within a list or a grid.

Usually only two templates are required : 1 for the normal grid / slider displays of products and 1 for the search autocompletion.

model

title

models are by default provided with the same value as the template and can be changed / ignored depending on your integration needs.

title

Search results for ‘your search’:

The current search query is configured as a variable in the narrative with : $.requests[0].searchQuery^

The title value to be displayed

bx_alternate_title

Corrected results for ‘corrected search’

The current search query is configured as a variable in the narrative with : $.requests[0].correctedSearchQuery^

Not needed in your template, only in the configuration of Search Title in Boxalino Intelligence Admin for search. In case of a corrected search, this title will be returned in the “title” parameter instead of the default title content. But on the side of your template, you always receive the correct content in the parameter “title” and therefore don’t need to implement another template for search.