Hello Retail API
For regularly updated information on the current state of the Hello Retail API, as well as a complete list of the methods available in the SDK, we refer to this source: developer.helloretail.com/sdk/
This article is, in contrast, not an exhaustive reference on these features, but is supposed to provide some insight, into when it might make sense to use our API, and when it might not. The objective is to make it more clear to you, if your shop could benefit from investing development resources in setting up the features provided by Hello Retail yourself, or if you would be happier with a more standardised approach, where Hello Retail is managing the setup of these solutions.
Introduction
Very broadly speaking, the tradeoff between a managed solution and an API-based setup, is a choice between ease of use on the one hand, and how smoothly the individual features, like Search and Recommendations can be integrated into your webshop on the other.
If you simply wish to utilise the features and data processing of Hello Retail, in order to potentially increase revenue on your webshop, but otherwise have little interest in, or time for, configuring every little detail on how the solutions are working, you can have us set up our best practice, without the need to really involve yourself in other concerns, besides how you want the elements to look, and where you want them to be placed.
With a managed solution like this, Hello Retail handles the layout and insertion of elements on your webshop, but with the limitation that these are invoked through JavaScript, with a Liquid template rendering the HTML. As with all services running JavaScript, some minor delay between when the page has finished loading and when the elements can be inserted, is unavoidable. As a further limitation in the managed approach, it also requires that the Implementation Team and Tech Support at Hello Retail are able to replicate and maintain functions like add to basket, compare products, put on personal wishlist and similar, that you may have added to your webshop. This has to be done in a manner, that can be executed inside the Liquid templates that form the basis of most of Hello Retail's frontend rendering.
Put differently, if your webshop is running complex functionality, and you are not able to provide us with a working frontend implementation that can be copied by Hello Retail, you might only be able to retain this functionality in the features provided by Hello Retail, if your developers use our API to return raw JSON product data, and then handle this in the same way as products on your own webshop/frontend.
Why a managed solution?
The obvious benefit for you with this approach is, that you will not need to spend a lot of time on complex details for setup and tracking, but rather can use our long-running experience with what works. Hello Retail will then simply output this, in the styling that is already used on your webshop. When you want to adjust or change anything, you get in touch with our support, and we will then handle this for you - given that the request is possible and meaningful to execute.
Why the need for an API based setup?
On the other hand, you should consider using our API, if the following applies to your webshop.
You are running complex functionality that is not exclusively defined frontend, but may require insight into and access to your own tools and databases.
The Recommendations, Search or Pages solution needs to be visually present and ready on your website at page load, with no extra delay (in most cases it should be said, that this delay is not very noticeable, but every shop performs differently, and what is acceptable for some is a shop stopper for others).
You require that Hello Retail should be working with, or supplemented by, other types of data, than what we are picking up with our own standard, cookie-based tracking ourselves. This tracking is listed in our documentation, as a requirement for a functional setup.
If you have a need to have more control over the behavior of the setup than what is usually practical or possible with our managed solution. While this is hard to truly define in exclusive terms, examples of this could be:
Show different prices in the search result based on different customer groups, or other types of segmentation of the visitors of the site.
Show different types of products in Recommendations, if people are visiting the shop (one domain), from different parts of the world.
Show free gift products on a category page if the visitor is getting to the page by way of clicking a link in your newsletter.
Two types of API solutions
When deciding what approach would best suit your requirements, it should be noted that we provide two, fundamentally different, ways of using our API. The difference isn't necessarily that great from a purely technical perspective, but in terms of having a predefined framework for the recommendation-part of your setup, the two options should be considered. This difference also persists when using the API for other features like Search and Pages but for those, the difference is more a matter of technical preferences.
Managed Recommendations through API
For this approach, you would be relying on already defined Recommendations, that are set up in the Hello Retail backend, and perform in accordance with a set of specific algorithms. Here you are simply calling the api, with a specific box-key pointing to the Recommendation that you want to have items returned from.
So in a simplified scenario for this, someone at Hello Retail has already created a Recommendation intended to show retargeted products on the front page and a Recommendation for a given product page, that shows related products with a price lower than the item itself. In order to get products returned from the system, it is then just a matter of calling the box that has the type of setup you are looking for. Typically this also requires that some parameters are passed along with the request, such as the product-url to which the system is supposed to find relations to.
So, here the overall process involves someone - typically an Implementation Specialist at Hello Retail - to define what the individual box-keys should do, so a dialogue about what you want to achieve from the setup, will have to be done before anything can be set up.
When specific boxes are involved in the API setup, it is also possible to return the Liquid template itself for the individual Recommendations.
Using managed recommendations like this, allows for some degree of flexibility, the elements can be present when your page is initialising and you can style the returned data in any way you see fit. But, if the type of algorithms that are defined in each box needs to be changed on a more dynamic scale, it would most likely give you more freedom, if you skip this step of setting up predefined boxes, and opt for simply calling the api without this anchor, as mentioned in the following.
Unmanaged Recommendations through API
It is also possible to call our API, and in the request itself define what it should do, what parameters it needs to take into account, and insert any filtering that needs to happen on the returned data. This approach offers the highest degree of flexibility, but it does require a great deal of knowledge about the internal workings of the Hello Retail system in order to be practically feasible. As there will be no parts of the setup that is defined inside the Hello Retail backend (as all calls are taking place on your side of things) there is also no real registration of what you are looking to achieve. For this reason, it is not really possible for our technical staff to help with any practical support of the setup, so any developer resources will have to be your own, making this an option only fully embraced by a handful of the many webshops using Hello Retail.
The technical differences between using the API with a managed- vs unmanaged setup is explained in greater detail in the documentation
If you have any questions about this guide, then please contact Support or your designated Account Manager about this.