API - Frontend (beta)

Warning

This API is currently in beta and only supported for customers who are part of the beta program. For others: use it at your own risk, and feel free to contact us if you have any questions!

What is it?

As explained here, the standard way of installing TasteHit on your shop is by using a Javascript Tag. This tag sends data to TasteHit to track interactions and receives data back from TasteHit to display product selection widgets. This is easy to install and does not require any coding skills.

If you want to use TasteHit in a custom way (integrate TasteHit in a mobile app or TV set-top box, integrate it as part of a CMS theme or plugin), you will use our HTTP rest API described here.

Sometimes you may want to use the best of both worlds: implement TasteHit using the Javascript Tag for simplicity, while easily adding new features or modifying the behavior of existing ones without rewriting everything. In that case the TasteHit Frontend API is what you are looking for. The Frontend API is exposed to you directly inside the browser once the TasteHit tag is loaded on the page. Go on any page of an online shop using TasteHit, open the Javascript Console (how to do this on Chrome), start typing TasteHit. and you will see a list of available functions:

JS console

This API allows you to perform different actions directly: from the current page from monitoring to querying TasteHit for products or resorting a list of products of your own.

How to use it?

In the installation section, we explain that the TasteHit tag loads asynchronously, after your page's HTML (its DOM) is ready. This is done with the following syntax:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
<!DOCTYPE html>
<html>
  <head>
    <title>Your awesome site's title</title>
  </head>
  <body>
    [...Loads of stuff here...]

    <script type="text/javascript">
    var _thq = _thq || [];
    _thq.push(['setId', 'CustomerX']);
    _thq.push(['trackPageView']);
    _thq.push(['trackEvents']);
    _thq.push(['detectChanges']);
    _thq.push(['displaySmartMenu']);

    (function() {
      var th=document.createElement('script');th.type='text/javascript';th.async=true;th.src=('https:'==document.location.protocol?'https://':'http://')+'www.tastehit.com/static/th.js';var s=document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(th, s);
    })();
    </script>
  </body>
</html>

Because of the fact that the tag's JS Code is loaded asynchronously, the TasteHit Frontend API is used in a special way: a _thq array is built beforehand (when the code is first run and before the TasteHit JS tag (https://www.tastehit.com/static/th.js) is loaded). The actions in this array are executed only when the Javascript Tag has finished loading.

The functions listed in the example tag above (e.g. trackPageView, trackEvents, detectChanges, displaySmartMenu) are all run after the parent page itself is loaded.

It is also possible to call these functions directly without using the _thqarray. For example, the following getJSONPopular function can be used to retrieve the 5 most popular products:

1
TasteHit.getJSONPopular(5, 0, function(err,res) {console.log(err,res);})

In order to do that, the TasteHit JS code itself needs to be loaded before. The full code would look like:

1
2
3
4
<script type="text/javascript" src="https://www.tastehit.com/static/th.js"></script>
<script type="text/javascript">
  TasteHit.getJSONPopular(5, 0, function(err,res) {console.log(err,res);})
</script>

Glossary

setId

Usage: setId(id)

Parameters:

  • id: your unique customer ID you can find in your profile in the TasteHit dashboard

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['setId', 'CustomerX']);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.setId('CustomerX');

Description

This function sets the customer ID globally in the tag. Calling this function is mandatory before any other frontend function can be used. In asynchronous mode, setId is always the first function to be run independent from the order in the _thq array.

setThUrl

Usage: setThUrl(url)

Parameters:

  • url: the TasteHit domain used for all requests

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['setThUrl', 'https://www.tastehit.com']);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.setThUrl('https://www.tastehit.com');

Description

This function is optional and doesn't have to be called in most cases. It sets the base url (domain) to be used for requests from the tag to TasteHit's servers. The default value is 'https://www.tastehit.com'. Unless someone from the TasteHit team asked you to call this function, you should not use it.

setReceiveDataFunction

Usage: setReceiveDataFunction(f)

Parameters:

  • f: the function to be called when an element with the custom-action-btn class is clicked on in a TasteHit widget.

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['setReceiveDataFunction', function(data){doSomething(data);}]);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.setThUrl(doSomething);

Description

This function is optional. It is executed when Custom HTML is set up and a user clicks on an element with the custom-action-btn class. In the example above doSomething is called with the object sent from the widget. More information on how this works in the custom HTML section.

setPidDetector

Usage: setPidDetector(id, parameterName)

Parameters:

  • id: the HTML ID of the element to be looked up in the page
  • parameterName: the name of the element's attribute which contains the Unique ID of the product

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['setPidDetector', 'productIdentifier', 'data-product-id']);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.setPidDetector('productIdentifier', 'data-product-id');

Description

This function is optional. It is used in certain situations to better detect product pages. The TasteHit tracking system uses different ways to detect product pages (page URL, PID inside page URL, metadata). It can happen that none of these systems work on some shops. The setPidDetector function will look for a div with the specified HTML ID and retrieve the product's Unique ID from parameterName. The examples above will correctly detect a product page if the following piece of HTML is present somewhere in the HTML page:

1
<div id="productIdentifier" data-product-id="63411"></div>

With this setting and the above tag, the tag will track that the page of product "63411" has been visited by the user.

displayWidget

Usage: displayWidget()

Parameters: None

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['displayWidget']);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.displayWidget();

Description

This function finds elements in the HTML code of the page, which have the TasteHit widget syntax (<div class="thRecommendations" data-widgetid="widgetX"></div>), and displays the widget at this location in the page.

When this function is called, the <div> needs to already be present on the page (likely generated in the backend/CMS). If you add the div after using Javascript, it will not be displayed.

In order to be able to insert a widget after the page is loaded use the detectChanges function hereunder.

detectChanges

Usage: detectChanges()

Parameters: None

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['detectChanges']);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.detectChanges();

Description

The goal of this function is to display TasteHit widgets in the exact same way as the displaywidget above. The only difference is that detectChanges checks for new TasteHit <div> elements on the page for 8 seconds. Using this function it is possible to add TasteHit <div> elements after the page is loaded.

displaySmartMenu

Usage: displaySmartMenu()

Parameters: None

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['displaySmartMenu']);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.displaySmartMenu();

Description

The goal of this function is to display the TasteHit Smart Menu widget on the page. The default tag given to you in your profile includes this line, but it is optional and you can comment it out.

hideSmartMenu

Usage: hideSmartMenu()

Parameters: None

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['hideSmartMenu']);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.hideSmartMenu();

Description

The opposite of the previous function: hides the TasteHit Smart Menu widget.

blockFurtherActions

Usage: blockFurtherActions()

Parameters: None

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['blockFurtherActions']);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.blockFurtherActions();

Description

This function prevents any other frontend API action from being executed. If you are using an event driven syntax for scheduling your frontend API calls, this function can be used to stop all action loops which are in place.

trackPageView

Usage: trackPageView()

Parameters: None

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['trackPageView']);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.trackPageView();

Description

This function sends a pageView event to save that a visitor visited a certain page. For better detecting product pages, look at the setPidDetector function above.

trackEvents

Usage: trackEvents()

Parameters: None

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['trackEvents']);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.trackEvents();

Description

This function activates the event tracking system so TasteHit can track clicks, carts and purchases. This function is not mandatory, but most algorithms and insights in the TasteHit dashboard will not work as intended. It is therefore recommended to always activate it unless you want to implement the tracking system in another way on your own using the functions below.

trackProductVisit

Usage: trackProductVisit(itemPid, f)

Parameters:

  • item_pid: the Unique ID of the product for which to track the visit

  • f: the callback function, called after the data is sent

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['trackProductVisit', 'pid1', function(a,b){console.log(a,b)} ]);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.trackProductVisit("pid1", function(a,b){console.log(a,b)});

Description

This function saves a product visit. This is the manual version of the trackPageView function. The difference is that you can specify the Unique ID of the visited item.

trackProductPurchases

Usage: trackProductPurchases(itemPid, type, f)

Parameters:

  • item_pid: the Unique ID of the product for which to track the visit

  • type: the type of action: the two actions supported are "cart" or "purchase"

  • f: the callback function, called after the data is sent

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['trackProductPurchases', 'pid1', 'purchase', function(a,b){console.log(a,b)} ]);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.trackProductPurchases("pid1", 'purchase', function(a,b){console.log(a,b)});

Description

This function saves a specific action (a "purchase" or a "cart" addition). This works the same way as the trackProductVisit function, with the the fact that you can specify the type of the action to be recorded.

getJSONRecommendations

Usage: getJSONRecommendations(nbr, score, f)

Parameters:

  • nbr: the number of products to be returned

  • score: the score. The value should be null for the first request. Subsequent requests should reuse the score which was sent back with the last product.

  • f: the callback function, called when the data is received. It contains two parameters: the first parameter is a boolean (true if the request was successful), the second parameter is the data returned in JSON format.

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['getJSONRecommendations', 5, null, function(a,b){console.log(a,b)} ]);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.getJSONRecommendations(5, null, function(a,b) {console.log(a,b);})

Description

This function requests a specific number of products sorted by the recommendations algorithm. It takes into account the context of the page and the user's browsing history to return products.

getJSONCatalogItems

Usage: getJSONRecommendations(nbr, score, f)

Parameters:

  • nbr: the number of products to be returned

  • f: the callback function, called when the data is received. It contains two parameters: the first parameter is a boolean (true if the request was successful), the second parameter is the data returned in JSON format.

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['getJSONCatalogItems', 5, function(a,b){console.log(a,b)} ]);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.getJSONCatalogItems(5, function(a,b) {console.log(a,b);})

Description

This function returns nbr products without sorting them in any specifc order.

getJSONHistory

Usage: getJSONHistory(nbr, score, type, f)

Parameters:

  • nbr: the number of products to be returned

  • score: the score. The value should be null for the first request. Subsequent requests should reuse the score which was sent back with the last product.

  • type: the type of action: the two actions supported are "visit", "follow", "cart" or "purchase".

  • f: the callback function, called when the data is received. It contains two parameters: the first parameter is a boolean (true if the request was successful), the second parameter is the data returned in JSON format.

Asynchronous:

1
2
3
var _thq = _thq || [];
_thq.push(['getJSONHistory', 5, null, 'cart', function(a,b){console.log(a,b)} ]);
/*...Load tag (async)...*/

Synchronous:

1
2
/*...Load tag (sync)...*/
TasteHit.getJSONHistory(5, null, 'cart', function(a,b) {console.log(a,b);})

Description

This function requests the last nbr products from the browsing history of the visitor. The type specifies the type of interactions to consider (can be null if we want to consider all interactions).

Comments