...
| Code Block | ||
|---|---|---|
| ||
{
"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:
...
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:
...
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
...
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.
...
| Code Block |
|---|
{
"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
...
| Code Block | ||
|---|---|---|
| ||
{
//...
"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:
...
| Code Block | ||
|---|---|---|
| ||
{
//...
"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
...
| Code Block |
|---|
{
"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
...
| Info |
|---|
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.
| Code Block |
|---|
{
//...
"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
...
| Code Block |
|---|
"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.
...
| Code Block |
|---|
{
//...
"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
...
| Code Block |
|---|
"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 |
| Info |
|---|
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. |
...
| Code Block |
|---|
{
//...
"items": [
{
"field": "products_group_id",
"value": "1234",
"role": "mainProduct"
},
{
"field": "id",
"value": "1234A",
"role": "subProduct"
},
//example for content
{
"indexId": "your_account_content",
"field": "id",
"value": "678",
"role": "mainContent"
}
]
} |
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”) |
| empty / [your account]_content | in case your item is not a product from the main product index, you can specify here another index (typically, for content, pur your account name then ‘_content’) |
LEVEL 1 - PURCHASE- RE-BUY
...
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
| Code Block |
|---|
{
//...
"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:
...
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?
...