9.2 Dokumentation: Heycommerce produkt tracking – Heyloyalty Support

Documentation and tracking script for HLBI

DISCLAIMER:
It’s your responsibility to implement the tracking script. Heyloyalty cannot be held accountable to any unique setup you may have on your website..

Note: When using the free-version of our abandoned_basket, you are restricted to just the abandoned_basket trigger and your data will only be saved for 7 days.

You have 2 options for sending data to your heycommerce database:

Implementing the tracking using javascript
Using our API to send information
Browserspecific script blocking
Multi-shop script

NB! To use HeyCommerce (and avoid getting 400 error respons), make sure your account has activated to the HeyCommerce feature.

To activate the feature go to “Listeintegrationer” on your Heyloyalty account. Activate the following integration: Heycommerce

Remember to set it up, using a productfeed that matches the productID’s send using the tracking script mentioned further down.

Implementing the Script

When using Heycommerce, it’s possible to have multiple lists responding to a single domain.

At the same time, it’s possible to have the tracking work on a single list. The latter is done by adding the trackingID as a third value in the script.

Using generic tracking script:

The tracking script looks like this:

<script type="text/javascript" language="javascript">
 var hlt;
 var BiTrackingLoaded = function (BiTracking) {
 hlt=BiTracking;
 BiTracking.initialize('INSERTAPIKEYHERE', INSERTSESSIONTIMEHERE, 'INSERTTRACKINGID');
 }
</script>
<script>
 (function (d, t) {
 var g = d.createElement(t),
 s = d.getElementsByTagName(t)[0];
 h = "https:" == document.location.protocol ? "https://" : "http://";
 g.src = h + 'bi.heyloyalty.com/hlbi.js';
 s.parentNode.insertBefore(g, s);
 }
 (document, 'script'));
</script>

INSERTAPIKEYHERE = is your Heyloyalty API key. You can find this under “Kontooplysninger” on your Heyloyalty account.

INSERTSESSIONTIMEHERE = Define how long a session lasts. Insert the number of minutes, the session needs to be before an event is triggered.

INSERTTRACKINGID = is your Heycommerce Tracking Id and it’s optional.
It will ensure tracking only applies to a single list.
You can apply it, if your account needs different trackingscripts to run on multiple lists.

NB! You can find your Tracking Id when you open Heycommerce, found in “Listeintegration”.

Events

To track events, you need to fire specific events from the site. The events must be placed somewhere within your javascript, anywhere from your site, whenever a specific page is loaded.

Make sure to only fire the event, from the correct corresponding page

hlt.visit(PRODUCTID, CATEGORYID, CATEGORYNAME);
This event should be fired from all pages (except "purchase confirmation").
This could be a specific productpage, category page or any page you wish to track customer behavior from (guides, subpages, blogpost).

On productpages you should send the PRODUCTID (productid is - among other things – used for product interest). If possible, send the CATEGORYID and CATEGORYNAME aswell (as a minimum, we need the categoryname to trigger category interest events).

On a category page, sending a categoryname allows you to use category interest triggers at a higher rate.

NB: If you have no parameters to send, you can send an empty hlt.visit event. This event should look like this:

hlt.visit();

If you're only able to send the categoryname, the event should look like this:

hlt.visit(,,CATEGORYNAME);

hlt.addToBasket(PRODUCTID, AMOUNT, CATEGORYID, BASKETID, CATEGORYNAME);
This event can be fired from either the Basketpage or every add-to-basket button. Both need to include purchase info.

If you add it to the basketpage, you need to fire the event for each product added to the basket.

hlt.removeFromBasket(PRODUCTID);
This event should be fired whenever a product is removed from the basket. It will update our end, notifying us that the product has been removed and should be added in case of an add-to-basket email.

hlt.purchasedBasket(BASKETPRICE,ORDERNUMBER);
This event is to be fired from the Basket-thank-you page after the customer completes their purchase. BasketPrice and OrderNumber is not require, but greatly improves possibilites.

hlt.pairEmail(EMAIL);
For pairing directly from a sign-up/sign-in form. This event is optional, if you don’t want to pair the email from sign-up forms.

We utilize a “pair-on-click” from every email/sms/heypush send from Heyloyalty. Whenever a customer clicks and is directed to your site, the pairEmail event will fire automatically

hlt.heartbeat();
For visit to pages without a specific product.
This event should should only be used to notify that the session is still alive. No tracking will be collected for triggering or segmentation.

Remember to place the data-events within a script-tag.

example:

<script>….

hlt.visit(945, 2);

</script>

Example - with visit event

<script type="text/javascript" language="javascript">
 var hlt;
 var BiTrackingLoaded = function (BiTracking) {
 hlt=BiTracking;
 BiTracking.initialize('INSERTAPIKEYHERE', INSERTSESSIONTIMEHERE, INSERTINTEGRATIONIDHERE);
 hlt.visit("PRODUCTID”,"CATEGORYID","CATEGORYNAME") }
</script>
<script>
 (function (d, t) {
 var g = d.createElement(t),
 s = d.getElementsByTagName(t)[0];
 h = "https:" == document.location.protocol ? "https://" : "http://";
 g.src = h + 'tracking.heycommerce.dk/hlbi.js';
 s.parentNode.insertBefore(g, s);
 }
 (document, 'script'));
</script>

Example - visit event
When using the visit event, the values a mandatory.
Example with only categoryName ('thisCategory'):
hlt.visit('', '', 'thisCategory');
This could be used for search results or category pages.

addToBasket event

when using addToBasket, ProductId and amount (number of products put into the basket) is required.
Example with CATEGORYNAME and no CATEGORYID, BASKETID:
hlt.addToBasket('ProductID', Amount, '', '', 'thisCategory');

Example addToBasket event

<script type="text/javascript" language="javascript">
 var hlt;
 var BiTrackingLoaded = function (BiTracking) {
 hlt=BiTracking;
 BiTracking.initialize('INSERTAPIKEYHERE', INSERTSESSIONTIMEHERE, INSERTINTEGRATIONIDHERE);
 hlt.addToBasket("PRODUCTID","AMOUNT","CATEGORYID","BASKEID","CATEGORYNAME") }
</script>
<script>
 (function (d, t) {
 var g = d.createElement(t),
 s = d.getElementsByTagName(t)[0];
 h = "https:" == document.location.protocol ? "https://" : "http://";
 g.src = h + 'tracking.heycommerce.dk/hlbi.js';
 s.parentNode.insertBefore(g, s);
 }
 (document, 'script'));
</script>

Example purchasedBasket event

<script type="text/javascript" language="javascript">
var hlt;
var BiTrackingLoaded = function (BiTracking) {
hlt=BiTracking;
BiTracking.initialize('INSERTAPIKEYHERE', INSERTSESSIONTIMEHERE, INSERTINTEGRATIONIDHERE);
hlt.purchasedBasket("BASKETPRICE","ORDERNUMBER"}
</script>
<script>
(function (d, t) {
var g = d.createElement(t),
s = d.getElementsByTagName(t)[0];
h = "https:" == document.location.protocol ? "https://" : "http://";
g.src = h + 'tracking.heycommerce.dk/hlbi.js';
s.parentNode.insertBefore(g, s);
}
(document, 'script'));
</script>

Alternatively, you can use:

hlt.syncInfo(TYPE, DATA)

Where type is in: addtobasket, removefrombasket, visit, pairEmail, purchasebasket and Data is a url encoded parameters examples:

hlt.syncInfo('addtobasket', '&productId=1&amount=2&categoryId=3');

hlt.syncInfo('removefrombasket', '&productId=1');

hlt.syncInfo('visit', '&productId=1&categoryId=3');

hlt.syncInfo('pairEmail', '&email=test@test.dk');

hlt.syncInfo('purchasebasket', '&basketPrice=1&orderNumber=1');

Example

When can you trigger emails from Heyloyalty?

The below options show the possible days from where you'll be able to trigger emails from Heyloyalty, using HLBI

//Last number for last_visit and purchase are the days since last visit / purchase

last_visit_7
last_visit_14
last_visit_30
last_visit_60
last_visit_90
last_purchase_7
last_purchase_14
last_purchase_30
last_purchase_60
last_purchase_90

//First number is the number of days we look at. The second parameter are the number of visits to a specific product in the period

product_interest_7_2
product_interest_7_3
product_interest_7_4
product_interest_7_5
product_interest_7_6
product_interest_7_7

Documentation Generic tracking through API:

Required:
All requests require the following parameters:
session
cookie
Optional: integrationID

Track product visits:
route is /visit/{apikey} (apikey is your Heyloyalty API key).
Requires following parameters:
session, cookie, productId, categoryId, categoryName, url

Example:

https://tracking.heycommerce.dk/visit/myApiKey
?cookie=b0919c4c-a4a6-44d8-b72b-7d0d4f9ec9ba
&session=61931939-8945-42e7-9929-21fd2aaaa1b9
&productId=202427
&categoryId=1
&categoryName=name
&url=https://www.heyloyalty.com/

Track product added to basket:
route is /addtobasket/{apikey} (apikey is your Heyloyalty API key).
Requires following parameters:
session, cookie, productId, amount, categoryId, categoryName, url, basketId

Example:

https://tracking.heycommerce.dk/addtobasket/myApiKey
?cookie=b0919c4c-a4a6-44d8-b72b-7d0d4f9ec9ba
&session=61931939-8945-42e7-9929-21fd2aaaa1b9
&productId=202427
&amount=1
&categoryId=1
&url=https://www.heyloyalty.com/
&categoryName=name
&basketId=myBasketId

Track product removed from basket:
route is /removefrombasket/{apikey} (apikey is your Heyloyalty API key).
Requires following parameters:
session, cookie, productId.

Example:

https://tracking.heycommerce.dk/removefrombasket/myApiKey
?cookie=b0919c4c-a4a6-44d8-b72b-7d0d4f9ec9ba
&session=61931939-8945-42e7-9929-21fd2aaaa1b9
&productId=202427

Track that session have been bought:
route is /purchasebasket/{apikey} (apikey is your Heyloyalty API key).
Requires following parameters:
session, cookie.
Can include parameters:
basketPrice, orderNumber

Example:

https://tracking.heycommerce.dk/purchasebasket/myApiKey
?cookie=b0919c4c-a4a6-44d8-b72b-7d0d4f9ec9ba
&session=61931939-8945-42e7-9929-21fd2aaaa1b9

Pair cookie with email:
route is /pairemail/{apikey} (apikey is your Heyloyalty API key).
Requires following parameters:
session, cookie, email.

Example:

https://tracking.heycommerce.dk/pairemail/myApiKey
?cookie=b0919c4c-a4a6-44d8-b72b-7d0d4f9ec9ba
&session=61931939-8945-42e7-9929-21fd2aaaa1b9
&email=minEmail

Adding IntegrationID
If you have several list and want your tracking only relates to a single specific list, you can use the integrationID for that specific list:
If you wish to use your integrationId, the route takes that as a parameter:

?integrationId=myIntegrationID

the rest of the parameters are then added:

Example:
https://tracking.heycommerce.dk/visit/myApiKey
?integrationId=myIntegrationID
&cookie=b0919c4c-a4a6-44d8-b72b-7d0d4f9ec9ba
&session=61931939-8945-42e7-9929-21fd2aaaa1b9
&productId=202427
&categoryId=1
&categoryName=name
&url=https://www.heyloyalty.com/

Sync old orders:

route is /api/createorder/{apikey}
Structure is a json object of the following format:

{
"email": "test@test.com",
"createdAt": "2017-04-04 04:04:04",
"products": [{
"productId": "1",
"amount": 1
},
{
"productId": "3",
"amount": 1
}]
}

Note that variationId and categoryId is optional, but can be added to the arrays.
"variationId": "2",

Obligatory fields are: createdAt, productId and amount.

Example

POST https://tracking.heycommerce.dk/api/createorder/MyAPIkey

JSON example
{
"email": "test@test.com",
"createdAt": "2019-10-31 04:04:04",
"products": [{
"productId": "1",
"variationId": "2",
"amount": 1
},
{
"productId": "3",
"variationId": "2",
"amount": 1
}]
}

Cross Domain tracking

Its possible to parse cookies and sessions from different domains that is done by parsing hccookie and hcsession parameters in the URL. These can be fetched from the current tracking by calling hlt.cookieId and hlt.sessionId.

browserspecific script blocking

It's possible to block trackingscript from the user browser. This will block our script as well. This is an extension normally installed directly on the users end and not something we can do anything to prevent.

Any service that works with javascript elements to track data will be subject to this and we are no exception.

This can, for instance, be a chrome extension like "uBlock".

Multi-shop script

if you have a webshop, where you need a single script to use different trackingdatabases, you can use the below script instead of the one noted above.

Remember, you will need to add the webshop URL with the referer-reference. What your webshop uses as referer is normally "www.yourdomain.com" or "yourdomain.com" (replace yourdomain.com with your specific URL)

You will need to do this for each eventtype (visit, addtobasket, purchasedbasket), like you would, if you only had one site.

The main difference is, you'll be able to do this

Example for visit events

Remember to replace:

WebshopnoX with you shop URL
IntegrationIDX with your integrationIDs

you also need to add API key, sessiontime along with product information

<script>
  var currentDomain = window.location.hostname;
    switch(currentDomain) {
    case 'webshopno1':
      trackingId = 'integrationID1';
      break;
    case 'webshopno2':
      trackingId = 'integrationID2';
      break;
    case 'webshopno3':
      trackingId = 'integrationID3';
      break;
    default:
      trackingId = 'integrationID1'
   }
</script>
<script type="text/javascript" language="javascript">
  var hlt;
  var BiTrackingLoaded = function (BiTracking) {
  hlt=BiTracking;
    BiTracking.initialize('INSERTAPIKEYHERE', INSERTSESSIONTIMEHERE, String(trackingId));
    hlt.visit("PRODUCTID”,"CATEGORYID","CATEGORYNAME") }
</script>
<script>
  (function (d, t) {
  var g = d.createElement(t),
  s = d.getElementsByTagName(t)[0];
  h = "https:" == document.location.protocol ? "https://" : "http://";
  g.src = h + 'tracking.heycommerce.dk/hlbi.js';
  s.parentNode.insertBefore(g, s);
  }
  (document, 'script'));
</script>

Multi-shop script

Comments