JS API Requests for Different Site Page Types
In order to use Yespo product recommendation algorithms and customize their display on your side (appearance of blocks, display pages, etc.), follow these steps:
- install the script on the site to track the behavior of site visitors;
- upload product data feed to your Yespo account;
- set up the recommendation algorithm in your Yespo account.
Examples of Requests
On the Home Page and 404 Page
eS('getRecommendations', {
'variantId': 'r554v778'
}, function(error, products) {
if (error) {
console.error(error);
return ;
}
});On the Product Page
eS('getRecommendations', {
'variantId': 'r554v778',
'productId': 'MX-1512\42'
}, function(error, products) {
if (error) {
console.error(error);
return ;
}
});On the Cart Page
eS('getRecommendations', {
'variantId': 'r554v778',
'productIds': ['123', '543534']
}, function(error, products) {
if (error) {
console.error(error);
return ;
}
});On the Cart Pop-up
Use the StatusCartPage event to determine the page type and display recommendations on the cart pop-up. Example:
eS('sendEvent', 'StatusCartPage');On the Categories Page
eS('getRecommendations', {
'variantId': 'r554v778',
'categoryKey': 'cK'
}, function(error, products) {
if (error) {
console.error(error);
return ;
}
});The JS API method is asynchronous, which allows not to wait for the execution of other functions on the site.
Request Parameters
Name | Type | Example | Description |
|---|---|---|---|
variantId | Required String | r262v361 | The unique ID of the recommendation variation in the Yespo account. |
productId | Optional String | MX-1512\42 | To pass the product ID from the page the user is on. Required parameter for recommendations using the product algorithm (similar products, products that were bought together with some items); for other types of algorithms, it is not necessary to pass. |
productIds | Optional | ['123', '543534'] | To pass a product ID or an array of cart product IDs. Required parameter for recommendations using the product algorithm (similar products, products that were bought together with some items); for other types of algorithms, it is not necessary to pass. |
categoryKey | Optional | Jackets | To pass the key of the category the user is in. Required parameter for recommendations using a categorical algorithm (personally for you in this category); for other types of algorithms, it is not necessary to pass. |
allFields | Optional Boolean | true\false | Parameter for determining which product attributes will be in the recommendation request: All (which are available in the product data feed) or only Required: |
Response Example
Upon successful submission of the request, you will receive a response similar to the following:
Response body | Type | Description |
|---|---|---|
JavaScript |
| • product_id - recommended product ID |
Important
Don’t edit the return value in the URL field for web tracking to work correctly.
Error Example
| Example | Type | Description |
|---|---|---|
| variantId r262v361 was not found in config | String | No such recommendation variant identifier was found. |
Important
Send the ProductImpressions event after calling and displaying the recommendations block for proper tracking.
Filtering Recommendations
Filtering recommendations through the JavaScript API allows you to show products on your site by filtering recommendations based on data from the feed or contact information stored on your side. For example, you can filter recommendations by the city of residence, clothing size, favorite brand, promotional offer, etc.
Filtering recommendations through JS API saves you from changing the filtering rules in the data source in Yespo account every time.
Request format:
eS('getRecommendations', {
variantId: 'r362v614',
'filters': {
'include': [{'name': 'city', values: ['Kiev','Kharkiv']}]
}
},
function(error, products) {
if (error) {
console.error(error);
return;
}
}
);Request parameters:
Name | Type | Description |
|---|---|---|
filters | Optional Object | A parameter that includes filtering rules. |
include | Optional List | Strict filtering: recommend only products according to the given parameters. For example, show only products of a certain brand. |
exclude | Optional List | Strict filtering: products with specified parameters are not shown. For example, do not show discount items. |
should | Optional List | Non-strict filtering: products with specified parameters shown in priority, others by default (if there should be 20 recommendations in the search results, 5 products with the specified parameters will be shown, the remaining 15 — without applying the filter). For example, include products from a new collection in recommendations. |
name | Required String | The name of the product parameter from the product feed. |
values | Required List | List of values to filter. The comma in values is the |
You can also define a field (parameter) by which product categories will be filtered in the feed for display in recommendations. To do this, specify the desired categoryField value in the request.
Example request:
eS('getRecommendations', {
variantId: 'r1673v2111',
categoryKey: 'BATHROOM',
categoryField:'tags_all_category_names'
},
function(error, products) {
if (error) {
console.error(error);
return;
}
}
);where tags_all_category_names guarantees a search across all values in the category tree.
To set the appearance of recommendation blocks in Yespo, please read this guide.
Updated 12 days ago