NAV Navbar
Logo
javascript

Introduction

This content and documentation are mostly relevant for developers who want to make changes to how addwish business 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 addwish business 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 addwish 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

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.

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

{"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 addwish 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.

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

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
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 addwish business already have the meta-data for this specific product. This will trigger the addwish wish list panel to slide out.

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 addwish business 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</a:

_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 addwish business.

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 addwish business 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 addwish business 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'
});

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

Arguments

Argument 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

Event binding

To bind functions to events within the addwish 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 addwish user information from our backend.
panel_build Triggered when the addwish wishlist panel is ready to be displayed. (This won’t be triggered if you have disabled the wishlist panel)