NAV Navbar
Logo
javascript

Introduction

This content and documentation are mostly relevant for developers who want to make changes to how Hello Retail works in their back- and front-end.

If you can’t find the answer you are looking for here, then please feel free to reach out to the Hello Retail support team via phone or email.

Tracking user

If you want to get personalised recommendations for a specific user, either via the REST or JavaScript API, you will need to supply the specific users Hello Retail tracking ID. This tracking ID is only available through the JavaScript API, so you need to get this value using the method specified here, for you to be able to send it to your backend for further use - in case you are using the REST API.

Get tracking user

ADDWISH_PARTNER_NS.api.user.get_tracking_id(callback_function);

Example:

ADDWISH_PARTNER_NS.api.user.get_tracking_id(function(trackingUserId) {
  // We will call your function, as soon as we have the tracking user id.

  // Here you can e.g send it directly to your backend using jQuerys ajax helpers:
  jQuery.post("/url/at/your/backend", {
    tracking_user_id: trackingUserId
  });
});

Simply call the get_tracking_id() function, specifying a callback function - this callback function will be called with the users tracking ID passed along.

Arguments

Argument Type Description
callback_function String The callback function you would like to be called after this function.

Register email on tracking user

Register an email address of a tracking user

ADDWISH_PARTNER_NS.regEmail(emailAddress);

Example:

ADDWISH_PARTNER_NS.regEmail(
  'customer@example.com'
);

To register a visitors email address on a tracking user.

Arguments

Argument Type Description
emailAddress String The email of the visitor

Opt in and out of tracking

Use this method to make Hello Retail stop tracking information about the current tracking user

ADDWISH_PARTNER_NS.api.set_tracking_optout(optout);

Example:

ADDWISH_PARTNER_NS.api.set_tracking_optout(true);

To opt out of tracking for the current user

Arguments

Argument Type Description
optout Boolean true to opt out, false to opt back in

Get the current state of tracking opt out

Use this method to get the current state of tracking opt out for the current user

ADDWISH_PARTNER_NS.api.get_tracking_optout();

Example:

var optout = ADDWISH_PARTNER_NS.api.get_tracking_optout();

Where optout will be a boolean indicating if the user is currently opted out of tracking

Recommendations

Using this API you can request product recommendations either directly on your site through JavaScript or via REST based HTTP requests from your own backend. In either case, the returned data will be a JSON structure, containing either rendered HTML or the individual data fields for each product. Notice that more than one set of recommendations can be requested at once by supplying more than one id. By requesting more than one set of recommendations at once the system makes sure that there are no duplicate products across the set.

Getting recommendations via REST

'https://www.addwish.com/api/v1/product-recommendation/getProductBoxes?trackingUserId=544e3f41e4b05e538f4512d2&format=json&ids=1234567890abcdef12345678,abc4567890abcdef12345432&url=http%3A%2F%2Fwww.example.com%2Fjeans%2Ffancy-jeans-002.html&crawledData[1234567890abcdef12345678][category]=Kitchen%20utensils'

The above request returns JSON structured like this:

{"result": {
  "1234567890abcdef12345678": {
    "result": [
      {
        "url": "http://www.example.com/shop/UltraBlender-2000.html#aw_source\u003dpb-1234567890abcdef12345678",
        "imageUrl": "http://www.example.com/images/UltraBlender-2000.png",
        "title": "UltraBlender 2000",
        "onSale": true,
        "price": 1699.95,
        "priceFormatted": "1.699,95",
        "oldPrice": 1999.95,
        "oldPriceFormatted": "1.999,95",
        "currency": "DKK",
        "category": "Kitchen utensils",
        "brand": "Indream"
      },
      {
        "url": "...",
        // ...
      }
      // ...
    ]
    },
  "abc4567890abcdef12345432": {
    "result": [
      {
       "url": "http://www.example.com/shop/NoFall-Solid.html#aw_source\u003dpb-abc4567890abcdef12345432",
        // ...
      },
      // ...
    ]
  }
}

If you specify “html” as the format, you will get a block of html rendered by the template configured by Hello Retail:

{"result": {
  "1234567890abcdef12345678": {
    "result": "<div>..."
  },
  "abc4567890abcdef12345432": {
    "result": "<div>..."
  }
}

Get product recommendations via a REST based HTTP request, to get recommendations data to work with in your backend.

HTTP GET Request

https://www.addwish.com/api/v1/product-recommendation/getProductBoxes?trackingUserId=<TRACKING_USER_ID>&format=<FORMAT>&url=<URL>&ids=<ID>,<ID>&crawledData[<ID>][<FILTER_NAME>]=<FILTER_VALUE>

Parameters

Parameter Required Description
ids Required List of recommendation box IDs. Separate multiple IDs with a comma.
url Optional This url specifies the product you want to find relations for. Note that you can also specify specific urls for each recommendation box.
format Optional Result format. Specify json to get a list of product data, instead of the default html renderer.
trackingUserId Optional Tracking user ID. When you want to get personalised recommendations for a specific user, you will need to supply that users Hello Retail tracking ID. This ID is only available through our JavaScript API, so you will need to get this value prior to thid and send it to your backend.
crawledData[ID][Filter name] Optional Filter values. You will need to specify both the ID for the recommendation box and the filter name. You can add multiple filters for each recommendation box. See more about filters below.

Details about passing filter values to getProductBoxes

In some situations it makes sense to filter which products are returned from the product recommendation engine. Maybe you want products cheaper than a certain limit, only products from a specific brand or category. This can be done by adding filtering to the recommendation engine. It is possible to pass values to use for filtering to the recommendation api call. The algorithm needs to be configured by Hello Retail before it can accept filter values as input. So get in touch with support@helloretail.com to get help configuring the algorithm.

All parameters are sent in the query string. The parameter name for passing filter values is crawledData. The filters must be sent per recommnedation box and you must supply the filter name. So passing a brand filter with the value “Nike” for a box with the ID 123 will look like this in the query string:

&crawledData[123][brand]=Nike&

In the Hello Retail backend categories are stored in a field called hierarchies that contains a list of category hierarchies the product is in. So a product can be in multiple hierarchies at once. As an example, a pair of woman sandals on sale could have the following hierarchies:

[ ["Shoes", "Woman"], ["On sale", "Woman"], ["Sandals"] ]

So these sandals are in the “Woman” subcategory below the “Shoes” category, they are also in the “Woman” subcategory below the “On sale” category, and finally they are in the “Sandals” category.

So when passing a filter value for filtering on hierarchies the passed filter value needs to follow the same structure but encoded as query string variables. So if we wanted to pass a filter saying that the products must be in the “Woman” subcategory below the “On sale” category the query string would look something like this:

&crawledData[123][hierarchies][0][]=On sale&crawledData[123][hierarchies][0][]=Woman&

Ass you can see you need to supply the index for the first level in the hierarchy but for the second you can pass an empty set of square brakets and the ordering of the parameters will deside the numbering.

It is possible to pass multiple hierarchies to one filter. So if you wanted to find “Woman” “Shoes” that are also “Sandals” you could pass the filter:

&crawledData[123][hierarchies][0][]=Shoes&crawledData[123][hierarchies][0][]=Woman&crawledData[123][hierarchies][1][]=Sandals&

Getting recommendations via JavaScript


ADDWISH_PARTNER_NS.api.recom.load(boxes, options, callback(id, content, tag), error_callback(product_box_id, tag, error_code));

Example:

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:
      category: "Kitchen utensils"

    },
    "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.
  }
);

Returns data if format = json

[
   {
       "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",
       // ...
   }
   // ...
]

Returns data if format = html

<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>

Do a JavaScript based function call, to get recommendations data to work with in your frontend.

Arguments

Argument Description
boxes A dictionary with recommendations box ids as keys and a `filter dictionary as values.
options A options Object.
callback A callback function that will be called once for every box that loaded succesfully.
error_callback An error callback function that will be called for every box that failed loading.

filter dictionary

Key Value
url This url specifies the product you want to find relations for.
<Filter name> Filter values.

options Object

Key Value
format Result format. Specify json to get a list of product data, instead of the default html renderer.
tag A string value that will returned to the callbacks when a specific call to load has completed.

callback Function

Value Description
recommendation_box_id The id of the reccommendation box that has finished loading.
data A list of product objects or rendered HTML as a string.
tag The tag supplied in the call to load.

error_callback Function

Value Description
recommendation_box_id The id of the reccommendation box that has failed loading.
tag The tag supplied in the call to load.
error_code Description of the error.

Search

You can call the Hello Retail search API endpoint via a plain http or https request.

The HTTPS syntax looks like the following: https://www.addwish.com/api/v1/search/partnerSearch?key=cbcad7ef-3848-4e01-9e21-c06d6518e6b8&websiteUuid=126678ad-8690-444a-b482-c7bdb6aaf940&rows=10&q=pika&format=json&start=0

HTTP request

https://www.addwish.com/api/v1/search/partnerSearch?key=cbcad7ef-3848-4e01-9e21-c06d6518e6b8&websiteUuid=126678ad-8690-444a-b482-c7bdb6aaf940&rows=10&q=pika&format=json&start=0

Returned JSON. Please note the actual resultes are returned in an array.

{
  "results": 33,
  "start": 0,
  "didTrackSearch": true,
  "result": [
    {
      "title": "Pikachu bamse",
      "imgUrl": "https://pokemonbutik.dk/wp-content/uploads/2016/12/Pikachu_bamse_1-150x150.jpg",
      "price": 100.0,
      "currency": "DKK",
      "url": "https://pokemonbutik.dk/butik/bamser/pikachu/#aw_source=ps-cbcad7ef-3848-4e01-9e21-c06d6518e6b8",
      "priceFormatted": "100,00",
      "description": "Pikachu plysdyr, er fremstillet i en flot kvalitet med broderede øjne, næse, mund og kinder. Alle børn elsker denne Pokémon maskot, der er den mest kendte Pokémon af dem alle. Han er en oplagt gave til enhver Pokémon fan.\n\n<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/Ir2bC_F8mFk\" frameborder=\"0\" allowfullscreen></iframe>",
      "keywords": "bamse, pikachu",
      "inStock": true,
      "extraData": {
        "itemNumber": "0001"
      },
      "productNumber": "21"
    },
    ...
    ...
  ]
}

Request values

Specification of the arguments parsed to the https://www.addwish.com/public-api/v1/search/partnerSearch.html end-point:

Field name Description
key Each search instance assigned for you website holds a search key that must be supplied. If you do not know your search key, please contact Hello Retail support
websiteUuid This is your specific website ID, If you do not know your search key, please contact Hello Retail support
q This is the search phrase, that you would like to query to the Hello Retail search engine
rows This should be a number, representing the number of results you would like to have returned. This is mainly used for pagination, so that we do not return the entire result set, but the number of results you specify in this parameter
start Specifies the starting position in the total result set, used for pagination
format Specify json in this parameter, to have a standard json format returned
fields A comma sep. list of what fields you would like to get in the response. If none specified you will get all standard fields back
return_filters Send true here, to have the API include data about filtering options. (See below)
filters[] Limit results to those mathing the speficied filter. The value must correspond to the query field from the the filters map in the response. This parameter can be specified multiple times. If multiple filters on the same property is speficied, the products returned will match any value within that property. If different properties are specified, the products must match one option from each property.

Returned values

Specification of the values returned in the response:

Field name Type Description
results int The number of results found in total, however the result only shows the number of results, specified in the input parameter “rows”
start int Shows the starting position, as stated in the “start” input parameter
result Array An array of search results
result[].title String The title of the product
result[].url String The url of the product
result[].price int The price of the product
result[].priceFormatted String The price formatted as a String, using formatting rules applied by Hello Retail - Please contact Hello Retail support, if you need other formatting options
result[].oldPrice int The price of the product, as it was before a price change
result[].oldPriceFormatted String The price of the product, as it was before a price change, formatted by using the formatting rules applied by Hello Retail
result[].isOnSale boolean Indicates whether the product is on sale or not
result[].currency String The currency for the con gured webshop
result[].inStock boolean Indication whether Hello Retail see’s this as in stock or not
result[].extraData.? - This might hold data, used for other purposes, like filtering and rendering
filters Map Each entry represents a filterable property on the products. The keys are the name of the property, and the value is a list of options.
filters.?[].title String The value that the results can be limited to. Usually human readable, except for hierarchies-filters. (See below)
filters.?[].count int How many results matches this filter
filters.?[].query String The string that should be send in a filters[] parameter, to limit the search to these results.
filters.?[].selected bool Whether this filter was used to limit the current results or not.
filters.hierarchies[].title String For hierarchies, the title is delimited with $, where each part represents a level of the hierachy. For example “Plumbing$Sinks$” specifies the category “Sinks”, which is a subcategory of “Plumbing”.
filters.hierarchies[].level int How deep this hirarchy (equals to the number of parts in the title).
filters.price.min String The lowest price within the products of the current search, if the price filter was not applied.
filters.price.max String The highest price withing the products of the current search, if the price filter was not applied.
filters.price.selectedMin String The currently selected minimum price.
filters.price.selectedMax String Thi currently selected maximum price.

Note that for filtering, only hierarchy, brand, price, and inStock is avaliable for filtering by default. If you require filtering on other properties, contact Hello Retail support to have them enabled.

Wish list

The wish list is by default triggered through the standard button, placed in one of the corners of the website. If you rather want to add a custom wish list button, you can do this by adding a JavaScript onclick event to an element of your choice.

This could be added to any element that you prefer to use, e.g <a>, <button>, <div>

Custom trigger for wish list panel

// Custom event to trigger the wish list panel to slide out, and add the current product to the wishlist.
ADDWISH_PARTNER_NS.link_click();

If you want your custom button on a product page, you can simply do this by calling the link_click() function, as Hello Retail already have the meta-data for this specific product. This will trigger the wish list panel to slide out and add the product to the wishlist.

// Custom event to trigger the wish list panel to slide out, without adding a product.
ADDWISH_PARTNER_NS.show_panel(true);

If you want to show the wishlist without adding the current product, you can use show_panel(true) instead.

Custom event for adding to wish list

// Custom event to add a product to the visitors wish list
ADDWISH_PARTNER_NS.add_to_wishlist({
  title: 'T-shirt',
  url: 'https://webshop.com/t-shirt.html',
  imgUrl: 'https://webshop.com/images/t-shirt-front-medium.png',
  price: 'DKK 100.00'
})

If you want your custom button to add a product to the wish list from any other page than a product page or if you wish to overwrite the product on the current page, you can simply do this by calling the add_to_wishlist() function and passing along an Object with the specific product attributes.

Arguments

Argument Type Description
title String The title of the product.
url String The canonical URL of the product.
imgUrl String A image URL of the product.
price String The price of the product.

Conversion tracking

The conversion tracking is used for Hello Retail to report sales performance metrics as well as training the algorithms to learn more about popular products being purchased together.

Tracking conversions

ADDWISH_PARTNER_NS.api.conversion.track_sale(receiptData);

Example using product urls and event binding:

_awev=(window._awev||[]);_awev.push(["bind_once", "crawl_completed", function() {
  ADDWISH_PARTNER_NS.api.conversion.track_sale({
    total: 499.32,
    orderNumber: '110-2347',
    email: 'customer@example.com',
    urls: [
      'http://example.com/shop/product-1234',
      'http://examplec.mo/shop/another-product'
    ]
  });
}]);

Example using product numbers and event binding:

_awev=(window._awev||[]);_awev.push(["bind_once", "crawl_completed", function() {
  ADDWISH_PARTNER_NS.api.conversion.track_sale({
    total: 391.17,
    orderNumber: '110-2348',
    email: 'another.customer@example.com',
    productNumbers: [
      '00098323',
      '00098345'
    ]
  });
}]);

Simply track a conversion, by parsing the key values of the order along to Hello Retail.

Arguments

Argument Type Description
total Number The total value of the specific order.
orderNumber String The unique order ID.
email String Email of the customer.
urls List of Strings The list of product urls included in this specific order.
productNumbers List of Strings The list of product numbers included in this specific order.

Cart tracking

It’s important that Hello Retail is correctly installed on your webshop before you can set up cart tracking, to use abandoned cart notification emails as a part of Triggered emails.

First, you have to allow Hello Retail to track cart contents. This information is needed to send out personalised abandoned cart email featuring the image, title and price of the product the customer has left behind.

Cart contents are tracked regardless of the email address of the customer is known or not.

Tracking a complete cart

Track a complete cart, using urls

ADDWISH_PARTNER_NS.api.cart.setCart({
  total: '123.50',
  url: 'https://webshop.com/cart/123456789',
  urls: [
    'https://webshop.com/t-shirt.html',
    'https://webshop.com/shoes.html'
  ],
  email: 'customer@example.com'
});

Track a complete cart, using product numbers

ADDWISH_PARTNER_NS.api.cart.setCart({
  total: '123.50',
  url: 'https://webshop.com/cart/123456789',
  productNumbers: [
    'p-1234',
    '2134h'
  ],
  email: 'customer@example.com'
});

Track a complete cart, with callback

ADDWISH_PARTNER_NS.api.cart.setCart({
  total: '123.50',
  url: 'https://webshop.com/cart/123456789',
  productNumbers: [
    'p-1234',
    '2134h'
  ],
  email: 'customer@example.com'
}, function() {
  console.log('Cart has been tracked');
  });

It’s recommended to track the entire cart once a visitor added anything to the cart.

Arguments

Argument Type Description
data Object See the list of possible keys below.
callback function Will be called without any arguments when cart tracking is finished. Optional.

Possible keys in data

Key Type Description
total String The total cart value. Optional.
url String A unique url to the current cart instance including products. Optional.
email String The email address of the customer/visitor. Optional.
urls List of Strings A list of canonical urls of all the products in the cart.
productNumbers List of Strings A list of unique product numbers of all the products in the cart.

Tracking when a visitor adds a product to cart

Track product added to cart, using url:

// Make sure to set the canonical URL of the product added to cart
ADDWISH_PARTNER_NS.api.cart.addProduct({
  url: 'https://webshop.com/t-shirt.html'
});

Track product added to cart, using product number:

// Make sure to set product ID of the product added to cart
ADDWISH_PARTNER_NS.api.cart.addProduct({
  productNumber: 'p-1234'
});

Register products that have been added to the shopping cart even if users don’t visit a cart page.

Arguments

Argument Type Description
url String The canonical URL of the product
productNumber String The unique ID of the product

Clearing a cart

Use the following method to clear a cart: ADDWISH_PARTNER_NS.api.cart.clearCart

Clear the cart

ADDWISH_PARTNER_NS.api.cart.clearCart();

Clear the cart, with callback

ADDWISH_PARTNER_NS.api.cart.clearCart(function() {
  console.log('Cart has been cleared');
  });

Subscribe to triggers

It’s possible to subscribe to the Price drop and Back in stock specific triggered email notifications. The use-case is that a visitor would like to opt-in and subscribe to either a price drop or back in stock email notification for a specific product, they can do this by filling in their email address in a specific form constructed for the purpose. You can use the following method to submit the visitor’s subscriber details to the triggered emails feature ADDWISH_PARTNER_NS.api.triggered_email.subscribe();:

Subscribe to a trigger

ADDWISH_PARTNER_NS.api.triggered_email.subscribe(email, type, <calback>);

// or

ADDWISH_PARTNER_NS.api.triggered_email.subscribe(email, type, url, <calback>);

Simple JavaScript example

ADDWISH_PARTNER_NS.api.triggered_email.subscribe("email@example.com", "price_drop", function(status) {
  if(status === "ok") {
    alert("Thank you! We'll let you know when this product drops in price.");
  } else {
    alert("Sorry, an error occured - " + status);
  }
});

Complete example w/ HTML

<form id="price_drop_form">
    <label>
        Type your email address to get a notification when this product drops in price:
        <input type="email" id="price_drop_email">
    </label>
    <button id="subscribe">Notify me</button>
</form>
<span id="status"></span>
<script>
    $("#price_drop_form").on("submit", function(e) {
        ADDWISH_PARTNER_NS.api.triggered_email.subscribe($("#price_drop_email").val(), "price_drop", function(status) {
            if (status === "ok") {
                $("#price_drop_form").hide();
                $("#status").text("Thank you! We'll let you know when this product drops in price.");
            } else {
                $("#status").text("Sorry, an error occured - " + status);
            }
        });

        // Prevent the form from actually submitting:
        e.preventDefault();
        return false;
    });
</script>

email is required and must be the email address of the visitor/user who wants to subscribe to a price drop or back in stock triggered email notification. E.g., email@example.com.

type is required and should be either the string "price_drop" or "back_in_stock"

url is optional; this should be the url for the product which to register the trigger. If omitted, the url of the current page is used. If used, this could be: "https://webshop.com/category/fancy-product.html"

callback should be a function. It will be called with whatever status returned from the Hello Retail server:

Status Description
ok: The email is successfully registered. We will send an email when the selected event occurs for the specified product. This code is also returned if the same email was already registered for the same event on the same product. We will only send one email when the event occurs, even if the email is registered multiple times.
invalid_email: The entered email is invalid.
invalid_type: The type parameter did not have an accepted value.
missing_product: We couldn’t find a product with the url you specified. (Hint: Check it using our product lookup)
not_enabled: You haven’t enabled the triggered email feature, or you haven’t enabled the trigger corresponding to the type.
unknown_error: An unexpected error occurred.

Event binding

To bind functions to events within the Hello Retail script, you can include the following javascript snippet anywhere on your site. It can be used at any time, before and after the script is loaded.

Bind function to action event

_awev=(window._awev||[]);_awev.push(["action", "name", callback]);

Example

var some_callback_method = function() {
    // You can do whatever you need in here.
    // ADDWISH_PARTNER_NS will be available.
    console.log("My callback is running!");
};

_awev=(window._awev||[]);_awev.push(["bind", "crawl_completed", some_callback_method]);
// The callback will now be run, when the crawl is completed

// If you don't need the callback to run after all:
_awev=(window._awev||[]);_awev.push(["unbind", "crawl_completed", some_callback_method]);

action must be one the following:

Action Description
bind The callback will be called each time the event ‘name’ occurs. If ‘name’ has already occurred, the callback will be called once immediately (no matter how many times ‘name’ previously occurred).
bind_once The callback will be called once, when ‘name’ first occurs. If ‘name’ has already occurred, the callback will be called immediately, and never again.
unbind If you no longer want to receive callbacks for an event, you can unbind it, by specifying the same name and callback as you used when binding. Note, that it must be the same instance of the function that was bound.

name are the event-name. You can currently bind callback to the following events:

Event Description
before_crawl Triggered before we look for product information on you site.
crawl_completed Triggered when we have finished looking for product information. (It will be triggered regardless of whether we actually found any info or not)
user_avail Triggered when the script has retrieved user information from our backend.
panel_build Triggered when the wish list panel is ready to be displayed. (This won’t be triggered if you have disabled the wish list panel)

Page tracking for SPA

If you are running your webshop as a Single-Page Applications (SPA), the Hello Retail partner script is typial not reloaded automaticaly when a visitors is triggeren a new page view. To ensure Hello Retail is picking up a new page view, via the partner script, you’ll have to ensure to call the reload() function available through the partner JavaScript API via ADDWISH_PARTNER_NS.api. This should happen every time a visitor navigates to a new page (the url changes). It should be called after the new content is available in the dom

Trigger reload, to track a new page-view:

ADDWISH_PARTNER_NS.api.reload()

Click tracking when using the REST or javascript API

Products returned from the Hello Retail product recommendation and search apis will contain links that have a tracking code appended to them in the fragment part of the url.

Example for search

https://shop.example.com/best-product.html#aw_source=ps-3335d0a7-5dd1-4044-ba76-d089348abf31

Example for product recommendations

https://shop.example.com/awesome-product.html#aw_source=pb-9cb4857e6ff3911d1c76ab6a

This tracking code allows the Hello Retail script to track clicks on products in search and recoms. When the api’s are used by the Hello Retail script these tracking links will be used in the generated dom. But a click handler is implemented so that the actual url that the customer is sent to when clicking the link does not contain the tracking fragment.

If you use the api directly you can leave the tracking fragment on the product urls. This will allow the Hello Retail script to automatically track clicks on the product recommendations or search implemented using our api solution.

Tracking without using the fragment

If you do not want to have the tracking fragment shown on the page the user lands on or the fragment does not work with your shop platform you can remove the fragment from the url. If you do this you will have to add a click handler to the products in your product recommendations or search. This click handler will make sure that click tracking is sent to Hello Retail even if the tracking fragment is not on the link. The click handler must set a cookie with the name “aw_source” and the value from the fragment in the tracking link. A bare bones implementation of this could look something like this:

<a href="https://shop.example.com/awesome-product.html" onclick="document.cookie='aw_source=pb-5cb4857e6ff3911d1c76ab6a';"> Awesome product </a>

You could consider implementing a click handler that finds the tracking fragment in the href attribute, sets it as a cookie and then navigates to the url without the tracking fragment.

Verify tracking

To verify that the click tracking works you can click one of the links that should track clicks with the network tab open in the browser developer console. The Hello Retail javascript will request the https://www.addwish.com/partner/init.html url. If tracking a search or product recommendation click that request should include clickedProductBoxId or clickedPartnerSearchConfigKey with the value from the tracking fragment.