Skip to content

Quick Start

This is a guide to get you started on using the REST API or JavaScript SDK to set up the Hello Retail search and recommendations.

You need an account to use the Hello Retail platform for your webshop. If you don't have an account, get in touch!

Enable activity tracking

The first step is inserting the following HTML snippet in the <head> element of your website pages: 

<script async src="https://helloretailcdn.com/helloretail.js"></script>
<script>
    window.hrq = window.hrq || [];
    hrq.push(['init', 
        {
            websiteUuid: "{website uuid}"
        }
    ]);
</script>
This allows our platform to track user activity to enhance product recommendations and searches. If you prefer serverside tracking, this is also an option.

Product Feeds

To utilize Hello Retails products, you need to make your shop's product data available. We support several data formats, the example below is done by providing a REST endpoint with a product catalogue in JSONL (JSON lines).

Example feed 

{"title":"{product title}", "url":"{product url}", "imgUrl":"{product image url}", "price":"{product price}"},
{"title":"{product title}", "url":"{product url}", "imgUrl":"{product image url}", "price":"{product price}"},
{"title":"{product title}", "url":"{product url}", "imgUrl":"{product image url}", "price":"{product price}"},
{"title":"{product title}", "url":"{product url}", "imgUrl":"{product image url}", "price":"{product price}"}
Read more about data feeds here: Setup and Data Examples. For many shop platforms, we have plugins that automatically create the feeds.

The next step is visiting My Hello Retail and navigating to Data Setup → Feeds and Add/Edit the feed for your webshop. In there, you can specify the URL for your endpoint and test that it is parsed as expected. The parsed feed can also be transformed in case you have special properties you need to attach to your products.

Search Integrations

With a managed search, you pick a template to base your search design on. Search Configurations

Templates offer a wide range of configurations. Scroll to general settings and choose the id of the search field. Styling options in the same table below.

<script>
    var options = {
        format: "html",
        return_filters: true,
        filters:["{hierarchy filters}"],
        sorting:[
            "{filter name} {asc|desc}", 
            "{filter name} {asc|desc}"],
        engine_options: {
            product: {
                current_count: 10,
                start: 0
            }
        }
    };

    hrq = window.hrq || [];
    hrq.push([
        "search",
        "{config_key}", // the search config key
        "Red running shoes",  // the search phrase
        options,
        function(products) {
            console.log(products);
        }
    ]);
</script>

The endpoint is available at https://core.helloretail.com/serve/search.

You use it by sending an HTTP POST request with a JSON body. The content type must be application/json or text/plain [^1]. There are some general settings at the top level, and then for each content type you want to search you must provide an object with settings for that content type.

Example of a request that searches the product catalog and the categories content:

{
    "query": "running",
    "key": "{search config id}",
    "format": "json",
    "products": {
        "returnFilters": true,
        "start":0,
        "count":10,
        "fields":["title","price", "url"],
        "filters": ["{filter name}"],
        //"sorting": ["price desc"]
    }
}

Product Recommendations

You configure this by going to My Hello Retail → Recommendations and create/edit a recommendation box on the list "Recommendations"

Scroll down and expand the Placement settings section to see the DIV code snippet used to insert the recommendations on your page. "Recommendations"

Example: 

<div id="hr-recom-your-generated-id-here></div>


hrq = window.hrq || [];
hrq.push([
    "loadRecom",
    // requests:
    [
        {
            // recom box key, found in the recommendations overview
            "key": "{recom box key}",
            "format":"html",
            "context": {
                "hierarchies":[["{hierarchy-1}","{hierarchy-2}"]],
                "brand": "{brand}",
                "urls": ["{product url}"]
            }
        }
    ]
    // Callback
    function(result) {
        // Do something with data here.
        if (!result.success) {
            console.error(result.message);
            return;
        } 
        for(let i = 0; i<result.results.length; i++) {
            console.log(result.results[i]);
        }
    }
]);

The endpoint is available at https://core.helloretail.com/serve/recoms.

You use it by sending an HTTP POST request with a JSON body. The content type must be application/json or text/plain [^1]. There are some general settings at the top level, and then for each content type you want to search you must provide an object with settings for that content type.

Example of a request that searches the product catalog and the categories content:

{
"websiteUuid": "{website uuid}",
"trackingUserId": "{tracking user id}",
"requests":[
    {
        // recom box key, found in the recommendations overview
        "key": "{recom box key}",
        "format":"html",
        "context": {
            "hierarchies":[["{hierarchy-1}","{hierarchy-2}"]],
            "brand": "{brand}",
            "urls": ["{product url}"]
        }
    }
    ]
}