Introduction
Boxalino Narrative API is a REST API supporting a configurable JSON data structure as input and output.
Several configuration can be defined and available in different URL end-points.
This document both describes the standard aspects of the API as well as the most commonly used default configuration which covers the vast majority of cases for the typical Boxalino WPO (Welcome, Search, Up-Sell and Cross-Sell).
End-point (URL)
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, batch and other Newsletter requests
ACCOUNT: your account name
PATH: a configurable path for your narrative, typically the value is “api”
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
As an first alternative, you can provide provide a parameter sessionId or _bxv instead of the profile id
As an second alternative, you can also not set the profileId parameter and instead set HTTP-Headers with either X-BX-PROFILEID (with the value of the _cemv cookie), or X-BX-CUSTOMERID (with the value of the customerId)
Above: Example query with ARC (Advanced Rest Client) Chrome extension
Before testing your integration with code, we recommend you test it with this extension to make sure it technically works.
Request JSON
Your JSON request (to be passed in the body of your POST request) is fully configurable.
We will not cover in this document how to configure it but will document how it works out-of-the-box in the case of the standard configuration which is automatically available with your account without any special configuration.
Base parameters
These parameters are always required, independently of the type of request you do:
{
"username": "your_account",
"apiKey": "your api key",
"apiSecret": "your api secret",
"dev": false,
"test": false,
"sessionId": "the visitor session id",
"profileId": "the visitor profile id",
"customerId": "the customer account id",
"widget": "search",
"language": "de",
"hitCount": 10
}
Name | Example value | Description |
|---|---|---|
username | your_account | The name of your account |
apiKey | [your api key] | if you don’t have an apiKey, please request it to Boxalino WARNING: your apiKey and apiSecret will not be the same for dev:true or dev:false requests |
apiSecret | [your api secret] | if you don’t have an apiKey, please request it to Boxalino WARNING: your apiKey and apiSecret will not be the same fir dev:true or dev:false requests |
dev | true/false | false for production data index access true for dev / stage data index access WARNING: you might use a different account for stage / dev in which case you might need to set this parameter to false but change your username (and apiKey and apiSecret) to match your stage / dev account |
test | true/false | false for your live configuration true for your current unpublished configuration (test mode) Your test configuration is based on the state of your configuration in the Boxalino Intelligence admin (intelligence.bx-cloud.com) which was set with the button “Save & Test” but not yet published. |
sessionId | [any unique string] | the string uniquely identifying the session of the user WARNING: this value should remain the same for the entire session and match the value of the cookie cems used by Boxalino tracker. Make sure to set the cookie if not set and to read it if already set by our tracker (or by yourself in prior requests). Make sure the cookie disappears at the end of the session. |
profileId | [any unique string] | the string uniquely identifying the visitor (should be the same for several visits if the user doesn’t flush his browser cookies) WARNING: this value should remain the same for the entire session and match the value of the cookie cemv used by Boxalino tracker. Make sure to set the cookie if not set and to read it if already set by our tracker (or by yourself in prior requests). Make sure the cookie last across many sessions for a minimum duration of 1 year. |
customerId | [the account id of the customer as provided in the customer export data] | (optional) if the user is logged in, the customerId should be passed to the request |
widget | home/search/navigation/similar/complementary/basket | the name of your configured widget (to get the list of your configuration widgets, go to the Boxalino Intelligence admin (intelligence.bx-cloud.com) in the main (Widget & Page Optimizers) view |
language | de/fr/en/it/… | the 2 letter language code WARNING: your data must be available in this language |
hitCount | 10 | the number of results you would like to be returned (in some cases like search, the number of returned hits might be smaller than the requested amount) |
Typical parameters
These parameters are often needed, independently of the type of request you do:
{
//... (see base parameters)
"offset": 10,
"groupBy": "products_group_id",
"returnFields": ["title", "discountedPrice", "products_brand"],
"filters": [
{
"field": "id",
"negative": true,
"values": ["123","456"]
},
{
"field": "discountedPrice",
"from": 10.80,
"to": 28.10,
"fromInclusive": true,
"toInclusive": true
}
],
"orFilters":false,
"parameters": {
"campaign":"mycampaign",
"User-Host": "62.2.185.11",
"User-Referer": "https://www.google.ch",
"User-URL": "https://www.yourside.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"
}
//...
}
These parameters are all optional as they can be defined as default values in the Boxalino Admin Configuration, however, it might be desired to set them explicitly in the query.
Name | Example value | Description |
|---|---|---|
offset | 10 | for pagination, in case you don’t want to retreive the first X results, but the results starting from a specific offset (offset = 0 means first result) |
groupBy | products_group_id | If you want the results to be grouped according to a specific property (often, we use the field “products_group_id” for this) |
returnFields | ["title", "discountedPrice", "products_brand"] | The list of fields that should be returned for each bx-hit in the response (see below the Bx-Hit section for more details) |
filters orFilters | a list of filters to be applied if the filters should be applied as an or or as an and | |
| “id” | the name of the field to be applied for the filter |
| true/false | should the filter be positively or negatively applied (return results matching the filters or not matching the filter) |
| [“a”, “b”] | a list of string values only needed for filters checking specific values can be left unset otherwise |
|
| a range of numerical values only needed for filters checking a range of numerical values only work for numeric fields from and to inclusive define if the provided number should be included or excluded in the filter matching logic |
parameters | { | configured parameters make sure to always provide:
do not have any automatic effect but might be require for specific configuration (for example: to indicate the current campaign which will help the system identify what are the best matches related to this campaign). |
Other parameters
The other parameters will be described below for each of the LEVEL 1 WPO: Welcome, Search, Navigation, Up-Sell, Cross-Sell, Re-buy and Individualize:
If you are not sure what WPO you are integrating, please contact Boxalino for clarification.
Response JSON
Your JSON response (returned as the content of your POST request) is fully configurable.
However, a base structure is fixed and present regardless of the configuration.
We will not cover in this document how to configure it but will document how it works out-of-the-box in the case of the standard configuration which is automatically available with your account without any special configuration.
Fixed base structure
The base structure consists of one JSON with a parameter “blocks” providing a list of blocks.
Each block has a list of subBlocks (which can be empty) in the parameter “blocks”.
There are some exceptions to this base structure (e.g.: batch requests) which are described in a later section which adds an encapsulating structure around this based structure, but even in such cases, the base structure is still provided inside.
{
"blocks": [
{
"blocks": []
},
{
"blocks": [
{
"blocks": []
}
]
}
]
}
The list of blocks corresponds to the layout blocks to be displayed to the user. Therefore, the Boxalino Narrative API is not a Data API (providing you detailed information about a model data object) but a Layout&Content API which provides you directly a list of blocks to be displayed to the user in the provided order.
Typically, to provide a grid-layout to the user, the first level of blocks represents the rows, and the second level (the children blocks of the main blocks) the cols. However, you are free to configure any structure that you want, the only important aspect is that the order in which the blocks are provided matches the order in which the elements are displayed to the user (typically considering a responsive design with elements appearing on a mobile view).
In addition, advanced technical parameters are provided in the root parameters: “performance” and “advanced”, go to the Annex “Advanced Response Parameters” to see the details.
Use other positions than the main “blocks”
If you define a parameter position in one of your Templates (e.g.: “left”), then, instead of being added with the other blocks in the main “blocks” property of the response, they will be set in a property name matching your position value (e.g.: “left”).
Here is an example response with a position “left” set in some of the returned blocks:
{
"blocks": [
{
"blocks": []
}
],
"left": [
{
"blocks": []
}
]
}
Block parameters
Block parameters are directly provided in the JSON object parameter of each block.
Their format varies (as exemplified below in the parameter1/2/3/4 but is often represented in the format of parameter1 as a list of strings).
{
"blocks": [
{
"parameter1": [
"a"
],
"parameter2": 0,
"parameter3": [
{
"a": "b"
}
],
"parameter4": [
false
],
"blocks": []
},
{
"parameter1": [
"a"
],
"blocks": [
{
"parameter1": [
"a"
],
"blocks": []
}
]
}
]
}
Typical Parameters
The following parameters are not fixed, but are automatically present in the standard (and most custom) configuration:
Name | Example Value | Description |
|---|---|---|
template | product_list | the name of the template which should be used to display the block and its parameters |
model | ProductList | (optional) the model that should be use in your MVC to manage the logic for this template rendering. In the majority of the cases you should not require any business logic and render the template directly, but in special situation (e.g.: to do a real-time look-up of a price before display) some controller method might be required in your template |
position | main | (optional) if you use a multiple column layout (e.g.: with search facets on the left column and results on the main column) this parameter will indicate for which column of your layout this block is destined. important: this parameter will change the structure of the response, see Fixed base structure above for details |
bx-attributes | as below | not all, but most of the blocks have bx-attributes properties and values to be mapped to your html tagging (see next section) |
bx-attributes: Tagging for your HTML
The property bx-attributes provide you with a list of names and values to tag your HTML (typically the DIV tag representing the block).
The name and values can be simply added to your div as additional attributes, except for the class, which should be added to the pre-existing class of the div.
The bx-attributes are provided as a list of “name” and “value” objects, as here:
[
{
"name": "data-bx-variant-uuid",
"value": "94370d66-a88b-461b-afc7-9347d946c7c8"
},
{
"name": "data-bx-narrative-name",
"value": "products-list"
},
{
"name": "data-bx-narrative-group-by",
"value": "id"
},
{
"name": "data-bx-item-id",
"value": "bq_campaigns_demo_kaltgepresst_mini"
},
{
"name": "class",
"value": "bx-narrative-root-item bx-narrative-item"
}
]
Here is the list of all the bx-attributes which can be returned, however it is recommended to simply loop through the array and add them to the div directly, so if this list changes over time, your integration won’t need to be modified to reflect the new changes:
Name | Example Value | Description |
|---|---|---|
data-bx-variant-uuid | 94370d66-a88b-461b-afc7-9347d946c7c8 | a unique identifier for a container block (a block which contains a list of dynamic elements) which is unique per display of the page |
data-bx-narrative-name | product-list | narrative name (typically defined as “product-list”) |
data-bx-narrative-group-by | products_group_id / id | the group by field which is used to group the dynamic elements returned in this container block. |
class | “bx-narrative”/”bx-narrative-item” | not all, but most of the blocks have bx-attributes properties and values to be mapped to your html tagging (see next section) |
data-bx-item-id | 1234 | the group by value of a specific element in the list of dynamic elements belonging in a conatiner |
data-bx-related-variant-uuid | 94370d66-a88b-461b-afc7-9347d946c7c8 | a unique identifier for a referred container block (a block which contains a list of dynamic elements) which is unique per display of the page (a referred container block means that the elements of the current block are related to the elements of another block of the page, for example, the product recommendations related to a banner appearing before) |
data-bx-related-narrative-name | product-list | related narrative name (typically defined as “product-list”) |
data-bx-related-narrative-group-by | products_group_id / id | the group by field which is used to group the dynamic elements returned in the related container block. |
data-bx-related-item-id | 1234 | the related group by value of a specific element in the list of dynamic elements belonging in a conatiner |
All these attributes, if returned, are required for the scroll and click behaviors to be properly tracked on the page.
The following HTML exemplifies what HTML tagging is required for our JavaScript Tracker to work optimally. You can see there that several classes are needed but static, while the following tags need to be dynamically injected from our response:
data-bx-variant-uuid (in the container div, from the parmaeter variantUuid)
data-bx-narrative-group-by (in the container div, from the parameter groupBy)
data-bx-item-id (for each hit, see Bx-hit section below for the field “groupValue”)
<div class="bx-narrative" data-bx-variant-uuid="08b13a09-9657-436f-be9a-28e329bcadf" data-bx-narrative-name="products-list" data-bx-narrative-group-by="id">
<div class="bx-narrative-item" data-bx-item-id="A">
<a href="https://example.org">
<img src="https://placeimg.com/180/400/animals/a">
<p>Product A</p>
</a>
</div>
<div class="bx-narrative-item" data-bx-item-id="B">
<a href="https://example.org">
<img src="https://placeimg.com/180/400/animals/b">
<p>Product B</p>
</a>
</div>
<div class="bx-narrative-item" data-bx-item-id="C">
<a href="https://example.org">
<img src="https://placeimg.com/180/400/animals/c">
<p>Product C</p>
</a>
</div>
</div>
Default Narrative Configuration
From now on, we will define the data structure appearing in the responses connected to standard aspects (such as bx-hit, bx-facets, bx-pagination, and bx-sort). The exact location in the response where these parameters will appear depends on your Narrative configuration.
If you are using the default configuration, their position is fixed and is described in the document “Integration Guide with default Narratives Configuration for Welcome, Search, Up-Sell, Cross-Sell, Re-buy and Individualize WPOs”. If you are doing a standard integration with the default Narrative configuration, we suggest you to switch to this document as main guide and to use the rest of this document only as reference material.
bx-hit : Product / Blog / Hit Block
The bx-hit parameter is typically inside the children blocks of the main block containing a list of products (search results, a slider of product recommendations, etc.).
A standard parameter “bx-hit” is provided with the key information about the hit (product, blog article, etc.):
{
"blocks": [
{
"blocks": [
{
"bx-hit": {
"id": "155524",
"groupValue": "155524",
"score": 88.96804809570312,
"title": "The title of the product",
"discountedPrice": 19.9,
"products_brand": [
"Könitz"
]
},
"blocks": []
},
{
"bx-hit": {
"id": "155525",
"groupValue": "155525",
"score": 88.96804809570312,
"title": "The title of another product",
"discountedPrice": 18.9,
"products_brand": [
"Apple"
]
},
"blocks": []
}
//...
]
}
]
}
Parameters of bx-hit:
Name | Example Value | Description |
|---|---|---|
id | 155525 | a string value matching the unique hit id returned. In case you use a group-by on another field, the id will match the top-scored matching id in that group. See Group-By details in general request parameters above. |
groupValue | 155525 | a string value matching the group by Value (in case of no group-by, the value will be the same as of the id). See Group-By details in general request parameters above. IMPORTANT: must be provided in the HTML tag as value for attribute “data-bx-item-id” as in HTML example above |
score | 99.82 | a numeric value indicating the score (the highest score is on top) the score depends of your Boxalino Optimization strategy and is logic is not described in this document |
other product fields | The fields indicated in addition depend on your configuration and the list of Return Fields in your request. See Return Fields details in general request parameters above. | |
| [1,2.5,3] | a list of numeric values in an array |
| 23.5 | one single numeric value |
| [“a”,”b”,”c”] | a list of string values in an array |
| “a” | one single string value |
LEVEL 1 - AWARENESS - WELCOME
The Welcome WPO consists in the integration of product recommendations on the home page or on general landing pages.
The home page doesn’t require any special parameter and the response doesn’t include any special parameters either, so the documentation of the prior sections covers it fully.
Some other start pages might need to pass some parameters (it is a best practice to have a landing page for each campaign defined in Boxalino admin) in “Request > Typical parameters” section above.
One parameter is often useful, “minHitCount” which should be set to the same value as the parameter “hitCount” to ensure that the system returns a minimum and a maximum (so exactly in fact) the number of recommendations requested.
LEVEL 1 - CONSIDERATION - SEARCH
The Search WPO consists of the integration of the search and navigation (product listing) pages.
We describe here first the case of navigation (as all the cases are also applicable for search) and then the case of Search (as it has several cases which are specific to search and not applicable for navigation).
NAVIGATION
The navigation widget consists of the display of a listing of products as well as facets (i.e.: filtering options), pagination, and sorting options.
The current category of the page should be set as a filter on the field “category_id” with the category id as a value.
Facets Request Parameters
These parameters are always required to set the value of a facet. It is also possible to set a facet request without setting a value for the facet (so that the facet will be included in the response) but it is also possible to do that directly in the Boxalino Intelligence Admin.
Facets with selected Value by the user:
Example of 2 facets set with values in the request without any additional parameters
{
//...
"facets": [
{
"field":"brand",
"values":["123", "456"],
"valueKey":"id"
},
{
"field": "discountedPrice",
"numerical": true,
"range": true,
"boundsOnly": true,
"from": 64.25,
"to": 179.001
}
]
}
Name | Example value | Description |
|---|---|---|
| products_brand | The name of the field (same as for filters) |
| [“a”, “b”] | a list of string values (same as for filters) only needed for facets checking specific values can be left unset otherwise |
| null/”id” | in case the facet value sent is not the indexed value, but an id, indicate here the name of the facet key used. |
|
| a range of numerical values only needed and only works for numeric fields numerical, range and boundsOnly should all be set to true from is inclusive but to is exclusive (typically, add 0.001 to the value to include the selected to value) |
Facets without selected Value by with additional parameters:
Example of a facet set in the request without values but with additional parameters (this is optional and can be done in Boxalino Intelligence Admin):
{
//...
"facets": [
{
"field":"products_brand",
"maxCount":100,
"minPopulation":5,
"sort":"1",
"sortAscending":false,
"andSelectedValues":true
}
]
}
Name | Example value | Description |
|---|---|---|
maxCount | 100 | the maximum number of facet values which can be returned (return only top N) |
minPopulation | 5 | What is the minimum counter value (population / number of response hits) for the facet value to be returned? By default 1 as any value having 1 hit or more is shown as facet value |
sort | “1”/”2” | sorting of the values of the facets: |
sortAscending | true/false | should the value be ordered in ascending or descending way (typically false for sort “1” to show highest counters first) |
andSelectedValues | true/false | when the user selects more than 1 value should the values be both matching each product or any of the value is enough? (only matters if UI makes it possible for the user to select more than one value) |
bx-facets: Facets in Response
The bx-facets parameter is typically within one of the main blocks of the response.
A standard parameter “bx-facets” is provided with the key information about the facets
{
"blocks": [
{
"bx-facets":[
{
"isBoundsOnly": false,
"field": "categories",
"url": "cat",
"isAndSelectedValues": false,
"values": [
{
"hitCount": 150,
"children": [
{
"hitCount": 150,
"children": [
{
"hitCount": 6,
"children": [],
"label": "Party & Scherzartikel",
"value": "470",
"url": "470"
},
{
"hitCount": 31,
"children": [],
"label": "Wohnen & Dekoration",
"value": "703",
"url": "703"
}
],
"label": "Geschenkartikel",
"value": "314",
"url": "314",
"selected": true
}
],
"label": "Default Category",
"value": "2",
"url": "2"
}
],
"isNumerical": false,
"sortCode": 2,
"isRange": false
},
{
"field": "products_brand",
"url":"brand",
"label": "Brand",
"values": [
{
"value": "kuhn rikon",
"url": "kuhn-rikon",
"label": "Kuhn Rikon",
"hitCount": 3,
"selected": true,
"show":true
},
{
"value": "gamaco",
"url": "gamaco",
"label": "GamaGo",
"hitCount": 1,
"show":true
}
// ...
],
"position": "left",
"enumDisplayMaxSize": 7,
"resetOnRemove": false,
"enumDisplaySize": 5,
"showCounter": "true",
"displaySelectedValues": "top",
"visualisation": "enumeration",
"valueorderEnums": "counter",
"isNumerical": false,
"isRange": false,
"isBoundsOnly": false,
"isAndSelectedValues": false,
"sortCode": 1,
"minDisplayCoverage": 0.8,
"order": 2
}
]
}
]
}
Parameters of bx-facets:
Name | Example Value | Description |
|---|---|---|
field | products_brand | The name of the field |
url | brand/cat | an encoded version of the field name to be passed to the url |
label | Brand | the label of the facet field to be displayed to the user (returned in the language of the request) |
values | the returned facet values | |
| kuhn rikon | the value as stored in your hits fields fro that field |
| kuhn-rikon Kuhn Rikon | url: the value as set in a SEO-friendly URL label: the value as it should be displayed to the user NB: these are not standard parameters, they will depend on the key values defined during your data integration for facets. For more information, please contact Boxalino. |
| ||
| 3 | the counter (population / number of hits) of this facet value |
| true | is this facet value currently selected by the user make sure to use this information for the display and not if it is selected or not in the request as it is possible that the facet was not set in the request but got set in the response (e.g.: for Search semantic filtering). is always true or not set (never set to false) |
| [an array of sub-values] | only for hierarchical fields, the children are sub-elements with the same structure (value, url, label, hitCount, selected and children) |
position | left/right/top/bottom | optional: to indicate in which zone of the display the facet should appear (e.g.: top facets versus left facets) |
enumDisplayMaxSize enumDisplaySize | 7 5 | How many values should be displayed before a “show more” link which expands the list of facets. There are two values and enumDisplayMaxSize > enumDisplaySize. All values should be displayed without “show more” link unless there are more than enumDisplayMaxSize values returned. In this case, only enumDisplaySize should be displayed before showing the “show more” link |
showCounter | true/false | Should the counter (population / number of hits) be displayed (typically between () ) next to the label or not |
displaySelectedValues | ““/top/only | ““ = the selected value(s) should appear within the list in their normal ordering top = the selected value(s) should appear on the top before the other non-selected values only = only the selected value(s) should appear and the others should not be displayed to the user |
visualization |
| what type of visualization should be done for the display (logic to be implemented in your templates) |
valueorderEnums sortCode | counter 1,2 | informative : in which logic the values have been ordered (custom is not ordered, to be done on your side) sortCode is similar but with same 1,2 information as in request |
isNumerical | false/true | indicate if the facet is a numerical range filter (e.g. for the price), typically either all 3 are set to false or all 3 to true |
isAndSelectedValues | false/true | when the user selects more than 1 value should the values be both matching each product or any of the value is enough? (only matters if UI makes it possible for the user to select more than one value) |
minDisplayCoverage | 0.8 | by summing the counters of all of the facet values we get a value indicating how many of the results are related to this facet. This threshold defines what is the minimum ratio (compared to the returned total hit count) so that facet is considered relevant in this context and should be indeed displayed. |
resetOnRemove | true/false | Can only be set to true in cases when the user has selected several values and the request was sent with the parameter andSelectedValue set to false (so the multi-value selection is an OR logic) If (and only if) set to true, it means that if the user removes a value from this facet, then all the values should be removed, not only the one the user selected to be removed. |
bx-pagination (bx-hitCount): Pagination in Response
The bx-pagination parameter is typically within one of the children’s blocks of a main block of the response.
"bx-pagination": {
"totalHitCount": 22,
"offset": 0,
"pageSize": 10
}
It is also possible to retrieve only the totalHitcount in a bx-hitCount parameter.
Name | Example value | Description |
|---|---|---|
totalHitcount | 22 | the total number of results |
offset | 0 | the current offset of the current results |
pageSize | 10 | the current page size |
User Sorting in Request
In order to order the results in a special way, you can set the sort parameter in your request.
{
//...
"sort": [
{
"field": "title",
"reverse": false
}
]
}
Name | Example value | Description |
|---|---|---|
sort | sort fields set by the user (should not be set at all for default sorting) sort fields are applied in the order provided (from the most to the least important) sort fields overwrite completely the ranking logic of Boxalino and should only be used if the user wants to change the ranking and not for other reasons | |
| title | the field to apply the sorting on WARNING: the field must be set not to be multi-value (multi-valued fields cannot be used for sorting) |
| true/false | true : biggest value first false : smallest value first |
bx-sort: User Sorting options in Response
The bx-sort parameter is typically within one of the children’s blocks of a main block of the response.
"bx-sort": [
{
"field": "title",
"reverse": true
}
]
Name | Example value | Description |
|---|---|---|
| title | the field to apply the sorting on WARNING: the field must be set not to be multi-value (multi-valued fields cannot be used for sorting) |
| true/false | true : biggest value first false : smallest value first |
SEARCH
In this section, we describe the aspects specific to the search.
All aspects of the Navigation also apply in search, if you have not already done so, please refer first to the Navigation Section before moving on further in this section.
The search results list has special types of layout for the case of no results and for the case of sub-phrases results (e.g.: “no results for your query ‘red tv samsung’ but here are some results for ‘red tv’ and for ‘tv samsung’ and for ‘red samsung’). We will not describe them here as they do not require any special request or response parameters (so structurally, they don’t require any special logic). Their layout (as well as the general default layout of the search) is not described here but in the document “Integration Guide with default Narratives Configuration for Welcome, Search, Up-Sell, Cross-Sell, Re-buy and Individualize WPOs”.
The main specific aspect of Search is the autocomplete (the display of textual and product suggestions while the user is typing). Such logic must be integrated in Ajax. We describe here the request and response to be done on your server and to be returned to the browser through Ajax.
It is highly recommended to simply pass through our response as it is already in JSON.
However, you might want to modify it to include information which is not available in Boxalino in real-time (such as the product price).
SEARCH-AUTOCOMPLETE REQUEST
{
//...
"acQueriesHitCount": 7,
"acHighlight": true,
"acHighlightPre": "<em>",
"acHighlightPost": "</em>"
}
Name | Example value | Description |
|---|---|---|
acQueriesHitCount | 7 | the maximum number of textual suggestions matching the typed query to be returned required field, the detection if it is a normal request or a autocomplete request is done based on the existance of this parameter. |
acHighlight | true/false | should the text match be highlighted |
acHighlightPre | <em> | what should be injected before the highlight |
acHighlightPost | </em> | what should be injected after the highlight |
SEARCH-AUTOCOMPLETE RESPONSE
The Search Autocomplete Response is a standard Narrative response with the exception of a special parameter “bx-acQuery” for the textual suggestions.
bx-acQuery
The bx-acQuery parameter is typically inside the children blocks of the container block of auto-complete queries (normally the first one).
the autocomplete textual suggestions can have many words
A standard parameter “bx-acQuery” is for each child block providing the key information about the suggested Search Terms
"bx-acQuery": {
"suggestion": "some term",
"highlighted": null,
"score": 36109.4609375
}
Parameters of bx-hit:
Name | Example Value | Description |
|---|---|---|
suggestion | red pants | the suggested query |
highlighted | optional : indicates which part of the query should be highlighted | |
score | 315 | a numeric score indicating the score of this query suggestion |
the bx-hit and bx-facets parameters in children blocks of the block with the parameter “bx-acQuery” will be automatically related to the current suggestion.
Typically, you can have both facets (to refine the query further) and hits (to show hits when the user does a mouse over the suggested term).
In addition, the autocomplete query returns a general list of hits which are the ones to show typically below the textual suggestion by default.
LEVEL 1 - EVALUATION- UP-SELL / CROSS-SELL
The Up-Sell WPO consists of the integration of product recommendations on the product detail page.
The Cross-Sell WPO consists of the integration of product recommendations on the basket page or on a pop-up appearing after a product is added to the basket.
The response of the Up-Sell and Cross-Sell is fully similar to the one of the Welcome and is therefore not re-described here.
UP-SELL / CROSS-SELL REQUEST
Both Up-Sell and Cross-Sell require the setting of Context-Items in the request.
In the case of Up-Sell, it corresponds to one value matching the current product detail page.
In the case of the Cross-Sell, it corresponds to the list of values matching the products already in the basket of the user.
{
//...
"items": [
{
"field": "products_group_id",
"value": "1234",
"role": "mainProduct"
},
{
"field": "id",
"value": "1234A",
"role": "subProduct"
}
]
}
Name | Example value | Description |
|---|---|---|
items | the list of context items (current product for product detail page and list of product in the basket for basket page) | |
| “id”,”products_group_id”,… | the identifier field On a product detail page, it might be “products_group_id” because the page is for a group of skus (different size / color options) and not for one specific product On the basket page it is always “id” as each product on the basket should be a specific sku |
| “1234” | the identifier of the product (value should match the provided field) |
| mainProduct / subProduct | (optional, should be set to mainProduct by default) if needed a value identifying the importance of the product in the list can be set (e.g.: the most expensive product of the basket is set to “mainProduct” and the other to “subProduct”) |
LEVEL 1 - PURCHASE- RE-BUY
The Purchase WPO consists of the integration of product recommendations on the account page or other special pages requiring the visitor to be logged in.
As the visitor is logged in, make sure to pass the customerId parameter with as value the account id (same value as in your customer data export).
These pages don’t require any special parameter and the response doesn’t include any special parameters either, so the documentation of the prior sections covers it fully.
LEVEL 1 - PURCHASE- INDIVIDUALIZE
The Individualize WPO consists of the integration of product recommendations on the e-mail (or other outbound messages) sent to the user.
A light-weight integration with our Composite Image / Redirection link Web-Service can be use which doesn’t require any integration of Boxalino Narrative API and only require the integration of special dynamic links in your e-mail templates: <a href=“LINK”><img src=“LINK”/></a>. Refer to our related documentation if you want to implement this light-weight integration.
The specialties of the Individualize integration are the following:
As you will request product recommendations for many different clients to be sent in E-mail, you need to make Batch requests grouping many (typically 500 - 1000 requests in one batch)
You should not use “main.bx-cloud.com” but “track.bx-cloud.com” as the main clouds should not receive heavy loads of requests at a specific moment which might affect the average request time performances!
BATCH REQUEST
{
//...
"batch": [
{
"customerId":"1234",
"parameters": {
"campaign": ["myCampaignA"]
}
},
{
"customerId":"4567",
"parameters": {
"campaign": ["myCampaignB"]
}
}
]
}
Name | Example value | Description |
|---|---|---|
batch | the list of customer requests to be processed all in one call | |
| 1234 | the customer Id |
| {“campaign”:[“myCampaign”]} | configured parameters, optional, needed for parameters specific to each customer. Global parameters which should apply to all customers can be provided as normal. do not have any automatic effect but might be require for specific configuration (for example: to indicate the current campaign which will help the system identify what are the best matches related to this campaign). |
BATCH RESPONSE
Instead of the standard Response JSON structure as described above:
{
"blocks": [
{
"blocks": []
},
{
"blocks": [
{
"blocks": []
}
]
}
]
}
The Batch request provides a different structure:
[
{
"customerId": 134,
"blocks": [
{
"blocks": []
},
{
"blocks": [
{
"blocks": []
}
]
}
]
}
]
So, instead of one object with a “blocks” parameter, the response is a list of objects each having a “customerId” parameter in addition to the “blocks” parameter.
The Inner Structure of the “blocks” parameters is unchanged.
Annex #1 - Advanced Response Parameters
In addition to the “blocks” parameter, other parameters are provided with some key technical information
{
"performance": {
"started_ts": "1583167301480",
"completed_ts": "1583167301560"
},
"blocks": [...],
"advanced": {
"0": {
"_bx_completed_ts": "1583167303413",
"_bx_started_ts": "1583167303345",
"_bx_request_id": "1aed4edd-30f8-4228-b612-f718478d5caf",
"_bx_variant_uuid": "9c51ee78-3ed9-469b-a992-e7baaf70c4e5",
"_bx_group_by": "products_group_id",
"General - bx_debug_level": "0"
}
}
}
The performance block indicates the start and completion timestamps (in ms) of your narrative API request. This is the total time spent on our servers (without counting the networking between yours and our servers).
To know what is the networking time, make a similar calculation on your side and deduce it the time spent on our server, this will give you information about the networking time.
Annex #2 - Advanced Request Parameters
The API supports also the settings of advanced parameters for special use-cases.
Correlations
What is it about?
Boxalino standard processes as well as your own custom projects in Google BigQuery can generate highly relevant data to be deployed and made available in Boxalino Real-Time Platform as described here: Open Data Science Lab (B/C DSL)
One of the most used table in the Open Data Science Lab is the “correlations” as documented here: correlations . It will be in your own BigQuery project in “[your_account_name]_lab.correlations”.
Most of the times these data will be used within the Boxalino configuration and will influence the algorithms deciding which products (or content) are returned in which order for each customer.
But sometimes, you might need to retrieve these data as they are saved in the “correlations” table. This can be done with configuration in the Boxalino Admin, but this can also be directly requested (without requiring any configuration) in your API request, which is the use-case we are documenting here.
What to send in the request?
In your request, you need to send another parameter called “correlations” as follows:
{
...
,"correlations": [
{
"origin": "boxalino_std",
"type": "xxx",
"source": "yyy"
}
]
}
it is an array of object, each with 3 parameters:
name | example value | comment |
|---|---|---|
origin | boxalino_std | (optional, will be ‘boxalino_std’ by default) To be set if you have loaded the data by yourself in the lab.correlations table with another origin value |
type | xxx | a string value as is in the type column of the correlation table |
source | yyy | a string value as is in the source column of the correlation table |
What will be in the response?
As the advanced parameters, there will be another parameter in the response also called “correlations”
{
...,
"correlations": [
{
"origin": "boxalino_std",
"typxxe": "xxx",
"source": "yyy",
"target": [
"zzz"
]
}
]
}
The values you can retrieve are stored in the array parameter “target” as in the example (“zzz”) above.
Add Comment