Javascript SDK

Setup

To use the HelloRetail JavaScript SDK you need to add the awAddGift.js script has to be present and initialized. When the script has been initialized the SDK will be attached to window and accessible through the variable name ADDWISH_PARTNER_NS like window.ADDWISH_PARTNER_NS. For the rest of this guide, we will only use ADDWISH_PARTNER_NS to mean the SDK.

Usage

To load any recommendations from Hello Retail you need to use the load function on the recom object, which is found inside the api object. This makes any call look like this ADDWISH_PARTNER_NS.api.recom.load.

ADDWISH_PARTNER_NS.api.recom.load(boxes, options, callback, error_callback);

The different arguments shown above are described below.

It is important to note that the API by default respond with HTML, which you can use directly on your site to show the Hello Retail recom boxes. If you wish to control the experience even further you can specify in the options object you wish to have JSON returned instead.

Note: It is important that you bundle the product recommendations to ensure no duplicates.

Argument	Description	Example
`boxes`	A dictionary with recommendations box IDs as keys and an object where you can add filters. The object can be empty, but needs to be added, see the example to the right.	`{ <box_id1>: {}, <box_id2>: { brand: <somebrand> }}`
`options`	An `options` object. It is only possible to specify a format which is either HTML or JSON, if nothing is specified HTML is returned. Additionally, you can specify a tag which you can optionally use to keep track of your requests.	`{ format: "json", tag: "some tag" }`
`callback(id, data, tag)`	A callback function that will be called once for every box that loaded successfully. It returns the id of the box, the data (either JSON or HTML) and the tag if you specified one.	`function (id, data, tag) { console.log(id, data, tag); }`
`error_callback(id, tag, error)`	An error callback function that will be called for every box that failed to load. It returns the id of the box, the tag you optionally specified and the error message.	`function (id, tag, error) { console.log(key, tag, error); }`

Examples

General exampleExample for Upsell recommendation boxes

ADDWISH_PARTNER_NS.api.recom.load(
    // boxes:
    {
        "1234567890abcdef12345678": { // This is the recommendation box ID, which is unique to your API call. Contact Hello Retail support to get your own ID.
        // Here, you can specify filter values, and other options for this specific recommendation box.
        // For example, you can specify the url of another product to get recommendations for:
        url: "http://www.example.com/jeans/extra-fancy-jeans-004.html",

        // You can specify filter values like this:
        hierarchies: [["Shoes", "Woman"]], // If needed you can specify multiple hierarchies, like for instance [["Shoes", "Woman"], ["On sale", "Woman"]]
        brand: "Nike"

        },
        "abc4567890abcdef12345432": {} // You can leave the options empty, to use the default url (the current page)
    },

    // options:
    {
        format: "json", // You can specify either "json" or "html" as format  
        (default is html)
        tag: "this can be anything" // The tag is optional.
    },

    // The following function will be called once for each set of boxes requested above.
    // The value of "id" will correspond to the recommendation box ID requested.
    // Data will contain ether rendered html or a list of products.
    function(id, data, tag) {
        // Do something with data here.
        // 'tag' will be the value specified on line 20 - "this can be anything"
    },

    // The following function will be called if there is an error. 
    // If the error is at the "box level" the id will be the id of the box
    // If it is a general error, the id will be undefined
    function(id, tag, error){
        //Do something with the error here
        // 'tag' will be the value specified on line 20 - "this can be anything"
    }
);

For Upsell recommendation boxes, we will need the information from the cart. In the example below, you will need to send a list of URLs for the urls parameter (note the plural version compared to the example above). If you would like to state to the customer how much they need to buy to get free shipping, you should also pass the price as an argument.

ADDWISH_PARTNER_NS.api.recom.load(
    // boxes:
    {
        "1234567890abcdef12345678": { // This is the recommendation box ID, which is unique to your API call. Contact Hello Retail support to get your own ID.
        // Here, you can specify filter values, and other options for this specific recommendation box.
        // For example, you can specify the url of another product to get recommendations for:
        urls: ["http://www.example.com/jeans/extra-fancy-jeans-004.html", "http://www.example.com/dress/pretty-dress-001.html"],
        price: 13213.33, 
        // You can specify filter values like this:
        hierarchies: [["Shoes", "Woman"]], // If needed you can specify multiple hierarchies, like for instance [["Shoes", "Woman"], ["On sale", "Woman"]]
        brand: "Nike"

        },
        "abc4567890abcdef12345432": {} // You can leave the options empty, to use the default url (the current page)
    },

    // options:
    {
        format: "json", // You can specify either "json" or "html" as format (default is html)
        tag: "this can be anything" // The tag is optional.
    },

    // The following function will be called once for each set of boxes requested above.
    // The value of "id" will correspond to the recommendation box ID requested.
    // Data will contain ether rendered html or a list of products.
    function(id, data, tag) {
        // Do something with data here.
        // 'tag' will be "this can be anything" from above.
    },

    // The following function will be called if there is an error. 
    // If the error is at the "box level" the id will be the id of the box
    // If it is a general error, the id will be undefined
    function(id, tag, error){
        //Do something with the error here
        // 'tag' will be the value specified on line 20 - "this can be anything"
    }
);

Example `data` values in callback

We send a data object which either contains HTML (default) or JSON if you specified this in the options object. The data object looks like following depending on what you specified.

HTMLJSON

<div>
    <div class="product">
    <a href="https://example.org/product-1">
        <h1>Product 1<h1>
        <img src="https://example.org/images/product-1.jpg">
        <span class="price">EUR 79</span>
    </a>
    </div>
    <div class="product">
    <a href="https://example.org/product-2">
        <h1>Product 2<h1>
        <img src="https://example.org/images/product-2.jpg">
        <span class="price">EUR 59</span>
        <span class="old-price">EUR 150</span>
    </a>
    </div>
</div>

[
    {
        "title": "Product 1",
        "url": "https://example.org/product-1",
        "currency": "EUR",
        "imageUrl": "https://example.org/images/product-1.jpg",
        "oldPrice": 0,
        "onSale": false,
        "price": 79.0,
        "productNumber": "prod-1",
        // ...
    },
    {
        "title": "Product 2",
        "url": "https://example.org/product-2",
        "currency": "EUR",
        "imageUrl": "https://example.org/images/product-2.jpg",
        "oldPrice": 150.0,
        "onSale": true,
        "price": 59.0,
        "productNumber": "prod-2",
        // ...
    }
    // ...
]

Javascript SDK

Setup

Usage

Examples

Example data values in callback

Example `data` values in callback