How to install Bunting

At its heart, Bunting is a JavaScript library that can be added to your HTML.

A master tracking code which should be installed on all webpages in which you want Bunting to learn about your user base. This script contacts Bunting, and sends tracking information to your own Bunting dashboard.

There are also page-specific tracking scripts to identify whereabouts on the website the end-user is (For example, to detect if they are on the Basket/Cart page, and what items they have in their basket).

Bunting requires this information to learn about your user base, and allows sophisticated and granular visitor targeting conditions to be set up.

This document describes each possible Bunting tracking code, and an explanation of the implementation requirements for each.

In addition, if Bunting is to learn about stock levels for products (as is the case in Scarcity messaging), then a Product XML feed of your entire product inventory should be supplied. The schema is discussed here: https://knowledgebase.bunting.com/xml-schema-guide/#more-443

Master Code

The below Immediately Invoked Function Expression is the core Bunting script. It must be added to all pages throughout your site. This enables knowledge about the user and their journey to be gained, as well as enabling us to deploy split tests and content.

The async and defer flags are set, meaning it will not block execution of your critical web content and not have an apparent effect on site render for the end-user.

<script type="text/javascript" id="bunting_script_1">(function(){if(typeof window.$_Bunting=="undefined")window.$_Bunting={d:{}};$_Bunting.src=("https:"==document.location.protocol?"https://":"http://")+"YOUR_BUNTING_ACCOUNT_ID.1.bunting.com/call.js?wmID=1";$_Bunting.s=document.createElement("script");$_Bunting.s.type="text/javascript";$_Bunting.s.async=true;$_Bunting.s.defer=true;$_Bunting.s.charset="UTF-8";$_Bunting.s.src=$_Bunting.src;document.getElementsByTagName("head")[0].appendChild($_Bunting.s)})()</script>

Please note YOUR_BUNTING_ACCOUNT_ID will be replaced with your actual account ID when your Bunting dashboard is set up.

Homepage

Please copy & paste this code on your homepage. Nothing needs to be edited – just copy & paste.

<script type="text/javascript"> if (typeof window.$_Bunting=="undefined"){window.$_Bunting={d:{}};}$_Bunting.d.hp = "yes";</script>

Product Page / PDP

Edit and paste this code on all product pages. Complete the unique product ID value with the corresponding ID from your database. This ID must match the ID of the product on the cart page, the order complete page, and in your product feed.

<script type="text/javascript"> if (typeof window.$_Bunting=="undefined"){window.$_Bunting={d:{}};} $_Bunting.d.vp_upc = ""; // Enter unique product ID used by your system here</script>

Category Page / PLP

Edit and paste this code on all category pages. The value is the category path used by your system. Nested categories are separated by > symbols. Eg: Electronics > Computers > Laptops. This value must match that within product feed.

<script type="text/javascript"> if (typeof window.$_Bunting=="undefined"){window.$_Bunting={d:{}};} $_Bunting.d.c = ""; // Enter the category name as used by your system here</script>

Basket / Cart Page

Edit and paste this code on your shopping cart page. Repeat the marked snippet of code with appropriate values for each product in a shopper’s cart. If the cart is empty then remove the bit: $_Bunting.d.cp.push([ .... ]);

<script type="text/javascript"> if (typeof $_Bunting=="undefined"){ var $_Bunting={d:{}}; } $_Bunting.d.cp = new Array(); $_Bunting.d.cdc = "";  // Delivery cost of the cart (number)
// Repeat the following code for each product in cart - start here
$_Bunting.d.cp.push([
  "", // Mandatory. Unique product ID used by your system (text). Eg: "7493". Must match the ID on your product page / product feed
  "", // Mandatory. Product price in GREAT BRITISH POUNDS (number), NO currency symbols. Eg: "349.95"
  "" // Mandatory. Quantity in cart (number). Eg: "1"
]);
// End cart product repetition here
</script>

Checkout Page

Please copy & paste this code on every page of your checkout. This does NOT include your cart or order complete page. Nothing needs to be edited – just copy & paste.

<script type="text/javascript">if (typeof window.$_Bunting=="undefined"){ window.$_Bunting={d:{}}; } $_Bunting.d.co = "yes";</script>

Order Complete / Thank you page

Edit and paste this code on any page that directly follows an order being placed (eg: your ‘Thank you’ page). Repeat the marked snippet of code with appropriate values for each product the customer has ordered.

<script type="text/javascript">
  if (typeof $_Bunting=="undefined") { var $_Bunting={d:{}}; }
  $_Bunting.d.uc = "yes"; // Do not edit
  $_Bunting.d.op = new Array(); // Do not edit
  // Edit from here onwards...
  $_Bunting.d.uoc = "";  // Unique order ID generated by your system (text)
  $_Bunting.d.odc = 0;  // Delivery cost of the order (number)
  // Repeat the following code for each product that has been ordered - start here
  $_Bunting.d.op.push([
    "",     // Unique product id (text). Eg: "7493". Must match the ID on your product page / product feed
    "",     // Product price in GREAT BRITISH POUNDS (number), NO currency symbols. Eg: "349.95"
    ""      // Quantity ordered (number). Eg: "1"
  ]);
  // End ordered product repetition here
</script>

Extra Information (Optional But Recommended)

This section is intended to go on any page after the visitor has identified themself. This could be a contact form completion page, an order complete page, or after logging in to an account. All values below are optional, but it is recommended you supply them if they are available.

Browsing Currency

Set the $_Bunting.d.cc value to corresponding 3-character ISO currency code, which the visitor is browsing. When they switch currency, change this variable.

  <script type="text/javascript">
  if (typeof window.$_Bunting=='undefined'){ window.$_Bunting={d:{}}; }
  $_Bunting.d.cc = 'GBP'; // Set visitor's currency to: 'GBP', or 'USD'
  </script>

Known Visitor Details

Does your website already have information about your visitors? Perhaps your database stores details that can be recalled and sent to Bunting when they log in to an account on your site? If so, enter these:

<script type="text/javascript">
if (typeof window.$_Bunting=='undefined'){ window.$_Bunting={d:{}}; }

$_Bunting.d.fn = ""; // The visitor's forename, if known
$_Bunting.d.sn = ""; // The visitor's surname, if known
$_Bunting.d.ea = ""; // The visitor's email address, if known
$_Bunting.d.g = "";  // The visitor's gender. Enter 'male' or 'female' if known, or leave empty

</script>

Account Log In Status

When a visitor logs in to your website, set the variable $_Bunting.d.uac to the unique account ID which your website uses to identify them (only applicable if your site supports a visitor login).

  <script type="text/javascript">
  if (typeof window.$_Bunting=='undefined'){ window.$_Bunting={d:{}}; }
  $_Bunting.d.uac = ""; // Unique account number / code when a visitor is logged in to their account on your site
  </script>

Email Subscription Status

By default, to comply with GDPR, the email subscription status of all visitors is set to optout, meaning they won’t be applicable to receive targeted emails from Bunting. When a visitor subscribes, set the variable $_Bunting.d.ess to subscribed (copy/paste the code below). If the visitor later decides to optout then you can let Bunting know by switching the value to optout. Read more on our GDPR compliance here: https://knowledgebase.bunting.com/bunting-customer-information-gdpr/#more-219

  <script type="text/javascript">
  if (typeof window.$_Bunting=='undefined'){ window.$_Bunting={d:{}}; }
  $_Bunting.d.ess = "subscribed"; // 'subscribed' or 'optout'
  </script>

XML Schema Guide

Bunting can learn about your product inventory to drive our product recommendation system, as well as using this data to enable social proofing & urgency messaging.

This document discusses the XML format required by Bunting.

Example Complete Feed

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
  <!DOCTYPE feed SYSTEM "https://YOUR_BUNTING_ID.1.example.com/feed-9.dtd">
    <feed>
      <product>
        <upc>abc123</upc>
        <ns>
          <ENG>iPad</ENG>
        </ns>
        <ps>
          <GBP>399.99</GBP>
        </ps>
        <u>https://example.com/products/abc123-ipad.html</u>
        <iu>https://example.com/main-images/ipad.jpg</iu>
        <i2u>https://example.com/secondary-images/ipad.jpg</i2u>
        <c>Tablets</c>
        <b>Apple</b>
        <oss>
          <GBP></GBP>
        </oss>
        <oe></oe>
        <rt>4.8</rt>
        <s>y</s>
        <gtin>3001234567892</gtin>
        <kw>black 250Gb</kw>
        <g></g>
        <cv1></cv1>
        <cv2>Extended Warranty</cv2>
        <cv3></cv3>
        <cv4></cv4>
        <cv5></cv5>
      </product>
        <product>
        <upc>xyz789</upc>
        <ns>
          <ENG>Revolving iPad Case in Pink</ENG>
        </ns>
        <ps>
          <GBP>34.99</GBP>
        </ps>
        <u>https://example.com/products/xyz789-ipad-case.html</u>
        <iu>https://example.com/main-images/ipad-case.jpg</iu>
        <i2u></i2u>
        <c>iPad Accessories</c>
        <b>FAB Cases</b>
        <oss>
          <GBP>5</GBP>
        </oss>
        <oe>1541078129</oe>
        <rt>3.2</rt>
        <s>4</s>
        <gtin>3001234567892</gtin>
        <kw>leather casual</kw>
        <g>female</g>
        <cv1>Free Screen Cover!</cv1>
        <cv2></cv2>
        <cv3></cv3>
        <cv4></cv4>
        <cv5></cv5>
        <a>yes</a>
      </product>
    </feed>

Specification

Please note For products with variations, you should only include the main product, which represents all variations. For example if “Men’s Pique Polo Shirt” is available in red and blue, you should only include the product once within the feed, using the title “Men’s Pique Polo Shirt”. Do not include the product multiple times for each variation.

Unique Product Code

The identifier for each product has to be unique within your account, and cannot be re-used. You can use any sequence of letters and digits for the product ID.

Requirement Tag Type Character Limit Example Value XML Example
Mandatory <upc> Text 250 Characters Max abc123 <upc>abc123</upc>

Product Name

This is the name of your product, which is required. Within the <ns>...</ns> node should be the name, in each relevant language accepted by your site, as demonstrated below. It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

The default language is required for all products. Secondary languages are highly recommended, but not mandatory.

Requirement Tag Type Character Limit Example Value XML Example
Mandatory <ns> Text 250 Characters Max iPad <ns><ENG><![CDATA[iPad]]></ENG></ns>

Product Price

The price of the product. Within the <ps>...</ps> node should be the price, in each relevant currency accepted by your site, as demonstrated below.

The default currency is required for all products. Secondary currencies are highly recommended, but not mandatory.

Important: If the product is on offer, then the price should be after the reduction, not before. So, for example, if a product was 300 reduced to 250, then the price should be 250

Requirement Tag Type Character Limit Example Value XML Example
Mandatory <ps> Number 250 Characters Max 399.99 <ps><GBP>399.99</GBP></ps>

Product URL

This is the web address of the product on your website. It must be an absolute URL, including the http:// protocol. Please do not include any tracking parameters. It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

Requirement Tag Type Character Limit Example Value XML Example
Mandatory <u> Text (include protocol) 250 Characters Max https://www.yoursite.com/products/abc123-ipad.html <u><![CDATA[http://www.yoursite.com/products/abc123-ipad.html]]></u>

Product Image URL

This is the URL of the main image for a product and is the first image that users see on product detail pages. It must be an absolute URL, including the http:// protocol.

If you have multiple different images of the product, submit the main image using this attribute and include a secondary image in the ‘Image 2 URL’ attribute. For best performance, images should ideally be around 700px by 700px.

It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

Required for all products.

Requirement Tag Type Character Limit Example Value XML Example
Mandatory <iu> Text (include protocol) 250 Characters Max https://example.com/main-images/abc123.jpg <iu><![CDATA[http://example.com/main-images/abc123.jpg]]></iu>

Image 2 URL

If you have an additional image for this product, include its URL in this attribute, including the http:// protocol. For example, if you have an image that shows the product from a different angle than the main image or if you have images of the packaging or the product in various settings. For best performance, images should ideally be around 700px by 700px.

It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

Required for all products.

Requirement Tag Type Character Limit Example Value XML Example
Optional <i2u> Text (include protocol) 250 Characters Max https://example.com/secondary-images/abc123.jpg <i2u><![CDATA[https://example.com/secondary-images/abc123.jpg]]></i2u>

Category

This attribute is the category path used by your system that contains the product. Nested categories should be separated by > symbols.

It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

Required for all products.

Requirement Tag Type Character Limit Example Value XML Example
Optional <c> Text 250 Characters Max >Electronics > Computers > Tablets< <c><![CDATA[Electronics > Computers > Tablets]]></c>

Brand

The name of the brand that manufactures the product. It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML

Requirement Tag Type Character Limit Example Value XML Example
Optional <b> Text 250 Characters Max Apple <b><![CDATA[Apple]]></b>

Offer Saving

Offer saving if this product is on offer (number). For example, if price is 250, but used to be 300 when not on offer, then this value should be 50

Within the <oss>…</oss> node should be the offer saving, in each relevant currency accepted by your site, as demonstrated below.

Requirement Tag Type Character Limit Example Value XML Example
Optional <oss> Text 250 Characters Max 59.50 <oss><GBP>59.50</GBP></oss>

Offer Expiry

If the product is on offer, then this attribute should be set to the expiry date. Dates can be submitted as Unix Timestamps only (timestamp info). If the product isn’t on offer, or if the offer doesn’t have an end date then simply enter 0.

Requirement Tag Type Example Value XML Example
Optional <oe> 10 digit number 1541078733 <oe>1541078733</oe>

Product Rating

If this product has been rated then enter the rating here. Rating values should be between 0 and 5. If your rating uses a different scale, then this should be converted. For example, a product rated 9 / 10 should be halved to make 4.5. Decimal places accepted.

Requirement Tag Type Example Value XML Example
Optional <oe> Number between 0 and 5 4.5 <rt>4.5</rt>

Stock Level

Is product in stock? Passing a number means: “yes, 14 units are remaining”. Passing the value y means units are remaining, but the number is unspecified. Passing n or 0 mean out of stock.

Requirement Tag Type Example Value XML Example
Optional <s> Alpha-numeric value 14 <s>14</s>

GTIN

Use the ‘GTIN’ attribute to submit Global Trade Item Numbers (GTINs) in one of the following formats:

  • UPC (in North America): 12-digit number such as 3234567890126
  • EAN (in Europe): 13-digit number such as 3001234567892
  • JAN (in Japan): 8- or 13-digit number such as 49123456 or 4901234567894
  • ISBN (for books): 10- or 13-digit number such as 0451524233. If you have both, only include the 13-digit number.

For products with multiple variations and, consequently, multiple GTIN numbers, you can separate each number with a comma. For example, a jumper in red, blue and yellow could have the following GTINs: <gtin>3001234567892,4001234567892,5001234567892</gtin>

Requirement Tag Type Character Limit: Example Value XML Example
Optional <gtin> 8-, 12- or 13-digit number (UPC, EAN, JAN or ISBN) 20 3001234567892 <gtin>3001234567892</gtin>

Keywords

Part of Bunting’s product recommendation algorithm involves matching keywords found in each product’s name to find similarities. However, if your product names are short or keyword-poor then we recommend including additional keywords in this field to compensate. These could be, for example, the name of a range that each product is part of, or a characteristic that plays in important role in visitor’s buying decisions, such as colour or size.

Well chosen keywords can notably improve product recommendations while supportive order data is being collected. However, conversely, poorly chosen keywords can damage them. Therefore we recommend including keywords only if you have good ones available.

Keywords can be separated by commas or spaces. It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

Requirement Tag Type Character Limit: Example Value XML Example
Optional <kw> Text 250 black 250Gb <kw><![CDATA[black 250Gb]]></kw>

Gender

Does product have a target gender, such as a lady’s jumper, or a man’s watch? If so, enter male or female. If the product is unisex (applicable to both genders) then leave this field blank. Any other value, including blank, will default to unisex.

Requirement Tag Format Example Value XML Example
Optional <g> ‘male’,’female’, or any other value including blank for unisex female <g>female</g>

Custom Values 1 – 5

Within the product recommendations that Bunting delivers to your website you may wish to have unique features or benefits displayed against some products but not others. To achieve this you can use Custom Values. Up to 5 values are accepted per product.

Values can contain HTML such as an <img />, they can be text strings that can be styled within your recommendation widgets, or be simple flag values to be caught by a recommendation widget IF statement. Anything within 250 characters length.

It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

Optional for all products.

Requirement Tag Type Example Value XML Example
Optional <cv1> - <cv5> Text Free Carry Case
3 Year Extended Warranty
<cv1><![CDATA[Free Carry Case]]></cv1>
<cv2><![CDATA[3 Year Extended Warranty]]></cv2>

Active

Is the product active and available to buy on the website? If not then pass the value no. Any other value, including blank, will default to yes.

Requirement Tag Format Example Value XML Example
Optional <a> ‘yes’ or ‘no’. Any value other than ‘no’, including blank, is taken as ‘yes’ yes <a>yes</a>

Installation checklist

The purpose of this checklist is to give you assurance that every component of Bunting was installed correctly. This will give you troubleshooting advice about how to double-check and resolve any issues that might crop up.  It’s useful to do this immediately after completing the install to give peace of mind that you’re ready to begin using Bunting.

At a high level, the following should be checked:

  1. Conversions are being tracked by Bunting.
  2. Abandoned Carts are being tracked.
  3. Products in your XML feed match those on your website.
  4. Page specific Visitor Targeting will work correctly.
  5. On the Homepage.
  6. On the Category pages.
  7. On the Product Pages.
  8. On the Cart page.

Firstly, let’s deal with conversions. 💰

If you have installed the Conversion Complete Page script. Go ahead and do the following test:

(more…)

What is a Product Data Feed and why do I need it?

Product feeds exist as a way of defining what products are within your inventory.

They include useful information such as the Product Name, Product Image, Stock Level, etc.

Bunting can read this data to begin attaching statistical probabilities that a user will purchase a particular product, and is the core of how the recommendation algorithm learns about your company.

What formats are supported?

We support XML and CSV/TSV formats.

What does it do?

This is where Bunting gains its knowledge of your products. This data is crucial to get the most value out of Bunting. A product feed with an updated index of products will allow the platform to provide much more efficiently.

Product feeds are ingested by default every 12 hours, and new products are then reasoned about.

(more…)