Setup for Qubit Aura

In this article...

We'll walk you through the steps you need to take to get Qubit set up on your site for clients delivering a mobile shopping experience through Qubit Aura.

The setup process

Setting up Qubit Aura on your site is a three-step process that must be completed in the following order:

  1. Add the UV API script
  2. Add the smartserve script
  3. Emit events

Don't forget to checkout our Events page for the full QP event specification.

Add the UV API script

Qubit's products and services make use of actionable data generated by the events emitted on your website. The UV API exposes a common interface for emitting these events.

We recommend that the UV API is included as an inline script on each page, at the top of the head tag, immediately after the <meta charset... /> tag and before the smartserve.js script.

By embedding the API in the head, synchronously, we can ensure that it is available for use by smartserve.js, or any other page script that emits or handle events, without polling or waiting for asynchronous scripts to load.

Add on every page:

<script>
!function(){function n(){function n(n){p.level=n}function e(n,e){p.info(n,"event emitted"),e=c(e||{}),e.meta=e.meta||{},e.meta.type=n,u.push(e),r(),v.listeners=f(v.listeners,function(n){return!n.disposed})}function o(n,e,o){function r(){return p.info("Replaying events"),t(function(){s(v.events,function(t){c.disposed||l(n,t.meta.type)&&e.call(o,t)})}),f}function i(){return p.info("Disposing event handler"),c.disposed=!0,f}p.info("Attaching event handler for",n);var c={type:n,callback:e,disposed:!1,context:o||window};v.listeners.push(c);var f={replay:r,dispose:i};return f}function t(n){p.info("Calling event handlers"),a++;try{n()}catch(n){p.error("UV API Error",n.stack)}a--,r()}function r(){if(0===u.length&&p.info("No more events to process"),u.length>0&&a>0&&p.info("Event will be processed later"),u.length>0&&0===a){p.info("Processing event");var n=u.shift();v.events.push(n),t(function(){s(v.listeners,function(e){if(!e.disposed&&l(e.type,n.meta.type))try{e.callback.call(e.context,n)}catch(n){p.error("Error emitting UV event",n.stack)}})})}}function i(n,e,o){var t=v.on(n,function(){e.apply(o||window,arguments),t.dispose()});return t}function s(n,e){for(var o=n.length,t=0;t<o;t++)e(n[t],t)}function c(n){var e={};for(var o in n)n.hasOwnProperty(o)&&(e[o]=n[o]);return e}function l(n,e){return"string"==typeof n?n===e:n.test(e)}function f(n,e){for(var o=n.length,t=[],r=0;r<o;r++)e(n[r])&&t.push(n[r]);return t}var u=[],a=0,p={info:function(){p.level>n.INFO||console&&console.info&&console.info.apply(console,arguments)},error:function(){p.level>n.ERROR||console&&console.error&&console.error.apply(console,arguments)}};n.ALL=0,n.INFO=1,n.ERROR=2,n.OFF=3,n(n.ERROR);var v={on:o,emit:e,once:i,events:[],listeners:[],logLevel:n};return v}"object"==typeof module&&module.exports?module.exports=n:window&&void 0===window.uv&&(window.uv=n())}();
</script>

For more information on using UV API, refer to our Github repository.

Add the smartserve.js script

The smartserve script is a JavaScript bundle hosted on Amazon’s CloudFront Content Delivery Network (CDN), which contains all the code that Qubit uses to collect data, compute segments, and serve experiences.

Add on every page:

<script src='https://static.goqubit.com/smartserve-{your-property-id}.js' async></script>

Qubit will provide you with your unique property Id at the start of the onboarding process.

To ensure the best possible data accuracy and experience delivery, it is important to place this script tag as early as possible on the page.

It is also recommended to put this in the page header with an async script tag, so that the script is non-blocking.

Please be aware that deploying the script through a tag manager, such as Google Tag Manager, or at the end of the file, can cause low-data capturing rates. To avoid this, we recommend adding tag prioritization. Refer to the documentation for your tag management solution for information about how to add this.

INFO: Qubit may maintain different versions of the smartserve.js script on production and staging environments.

Emit events

By emitting the right events at the right time on your website, you will generate a large amount of data that is actionable by Aura and other Qubit products and services.

Emitting an event involves using JavaScript to call the UV API:

uv.emit(type, [data])

To ensure our scripts can consume information about the page and the visitor in a reliable way, your events must conform to our event types schema and payloads.

In the context of Qubit Aura, events are used to:

  • Collect product data
  • Train our machine learning models on product information, visitor journeys, and behavioral outcomes
  • Power reporting on goals such as, Conversion Rates, engagement, and revenue uplift

You can listen for events in the browser and react to them in real time, or wait for them to be sent to our servers, where they will be processed and stored, and used to power our products and services.

Example:

<!-- Emit events anywhere on your page -->

<script>
  uv.emit('ecView', {
    type: 'product'
  })
  uv.emit('ecProduct', {
    eventType: 'detail',
    product: {
      productId: '1209012233',
      name: 'Stainless Steel and Leather Watch'
    }
  })
</script>

INFO: Before any event is sent to the backend, smartserve.js will add context information stored in cookies and meta information such as the URL of the page. This data will be available to query.

Events required for Qubit Aura

Refer to the following table for information about which events must be emitted on your website:

Event Name

Description

Requirements

ecView

Reports a page view

Must be emitted on every page before any other event and with the type field populated

ecProduct

Reports a product loaded on a page

Must be emitted on product detail pages

ecBasketItemTransaction

Reports the details of each item in the basket

Must be emitted on the transaction confirmation page

ecBasketTransactionSummary

Reports a transaction summary

Must be emitted on the transaction confirmation page

Refer to the following sections for field-level requirements for the aforementioned events.

ecView

The ecView event reports a page view and is a special event because it is required by smartserve.js for data collection and processing. It is therefore essential that every page emits an ecView event and that it is emitted before any other event.


Emit ecView events on every page.


DANGER: Any events emitted before the first ecView event are considered invalid. Web and mobile applications emit view events whenever a view is rendered.

Required fields:

  • type
  • language
  • country
  • currency

Example schema

Field (JS Data Type)

Description

type (String)

Reports the page type, e.g. home, category, search, product, basket, checkout, confirmation, help, contact, registration, content, account, or other

language (String)

The language used to render the page in this view, which must be an IETF language tag

country (String)

The selected country for the view, which must be an ISO 3166-1 alpha-2 code, e.g. GB, FR, US

currency (String)

The currency used to render prices on a page for the view, which must be an ISO 4217 currency code

Example JavaScript

uv.emit('ecView', {
  type: 'home',
  language: 'en-us',
  country: 'US',
  currency: 'USD'
})

Setup guidelines

type
  • Use only lower-case characters
  • Custom names can be used for unique page types that are not covered by our recommended e-Commerce page types such as home, category, product
language, country, currency
  • Language should be a string with a BCP 47 language tag, such as 'en-us', 'fr' or 'en-gb'
  • Possible currency values are the ISO 4217 currency codes, such as 'USD' for the US dollar, 'EUR' for the euro, or 'GBP' for the GB pound
  • Only a subset of languages work with Aura, as of writing English, Spanish, French, German, Italian, Portuguese, Dutch, Finnish and Brazilian are supported

ecProduct

Product events report a product loaded on a page. This could be, for example, a main product, a linked product on a product detail page, a product in a listing page, or search page.


Emit ecProduct events on product detail pages with eventType set as detail.

WARNING: It is not necessary to emit ecProduct on product listing pages.

INFO: Some data points such as productId must come from QProtocol. Other data points can come from either QProtocol or a product feed. Refer to the Data source column in the following table.


Required fields for product detail pages:

  • product.productId
  • product.sku
  • product.name
  • product.stock
  • product.price
  • product.description
  • product.url
  • product.images
  • product.categories
  • product.eventType

Example schema

Field (JS Data Type)

Description

Data source

product.productId (String)

Id to identify a product and all of its size, color, pattern, material, age, group, gender variants

QProtocol

product.sku (String)

Unique product identifier to distinguish it from variants

QProtocol/Product feed

product.name (String)

The product’s name, which should match the name shown on the product page

QProtocol/Product feed

product.stock (Number)

The number of available units in stock

QProtocol/Product feed

product.price.value (Number)

The price value, rounded to 2 decimal places

QProtocol/Product feed

product.price.currency (String)

The ISO 4217 currency code, e.g. GBP, USD

QProtocol/Product feed

product.description (String)

An accurate description of the product, which should match the description on the product page

QProtocol/Product feed

product.url (String)

The URL of the product’s landing page

QProtocol/Product feed

product.images (Array of Strings)

An array containing the URLs of the product’s images

QProtocol/Product feed

product.categories (Array of Strings)

A list of one or more product categories the product belongs to. Each category is a full category path, with each level separated by >

QProtocol/Product feed ¹

product.eventType (String)

The type of product event

QProtocol/Product feed

DANGER: ¹ Can be taken from a product feed only if the categories in the feed are a one-to-one match with the categories coming from QProtocol.

Example JavaScript

uv.emit('ecProduct', {
  product: {
    productId: 'SB2455_MOONROCK',
    sku: '5056001270695',
    name: 'Thermodynamic Run Leggings',
    price: {
      currency: 'GBP',
      value: 34,50
    },
    stock: 20,
    description: 'These technical leggings take thermal to a new level with colour pop panelling. Constructed in thermal fabric that holds in just the right amount of warmth, while helping to enhance breathability when you sweat.',
    url: 'http://www.sweatybetty.com/clothing/bottoms/leggings/multi-thermodynamic-run-leggings/',
    images: [
'http://906d39712c1aa37a1faa-e6ffe6e749ba3f6c3a70e2b2a58bd050.r52.cf3.rackcdn.com/images/products/medium/sb2455_moonrock.jpg'
    ],
    categories: [
      'Clothing > Leggings',
      'Activity > Run > Running Pants > Leggings',
      'Flash sale'
    ]
  },
  eventType: 'detail'
})

Setup guidelines

product.productId
  • You can include certain attributes, such as color or pattern, but not size, as part of the Id, e.g. SB1799B_BeetleBlue
  • This is not the sku. See On Product Ids vs SKUs for more information
  • Keep the value the same when updating your product data
  • Use only valid unicode characters
  • Don't use if your products differ by design elements that aren't represented by the above attributes
product.price
  • product.price.value must be rounded to 2 decimal places. See Examples of rounding for more information
product.stock
  • Should only be populated when the product is in stock and the exact number of available units is known
  • Should be NULL if the product is in stock but the exact number of available units is unknown
  • Should be 0 if the product is out of stock
  • Where different product variants have different stock levels, use the maximum stock level
product.url
  • The URL can start with http or https
  • If the URL is not provided, we will fallback to page URL where the event was collected
  • Should be the absolute path and NOT the relative path
product.images
  • The main image you want to use to display the product must be the first element in the array
  • Our recommend minimum image resolution is 375 x 375 pixels. The recommended size is 300kB
product.categories

DANGER: It is critical that product.categories is implemented precisely according to our guidelines. See Using Product Categories for more information.

DOs
  • Do provide only the most relevant category, or, alternatively, provide all of categories at once if that's easiest
  • Do provide different categories on different pages, to match the context.

    For example, it is acceptable to send New Arrivals > Clothing if visitors arrived via the New Arrivals menu item, and also acceptable to send Clothing > Sweaters > Short Sleeve Sweaters if visitors arrived via the Clothing menu item

  • Do implement a human readable category name that is formatted for display purposes. It can't be a technical term such as 457, SHOP/NW/CL or B_CLOTHING
  • Do use any number of levels required, e.g. a > b or a > b > c > d are both OK
  • Do match your categories with your website's breadcrumbs. We recommend this approach, because it will make the content more familiar to customers
DON'Ts
  • Do not include the top level category such as Home or Shop in the category path
  • Do not include the name of the product in the category path
  • Do not use View all in your category structure, for example Tops > View all. Instead, use Tops

product.eventType
  • Strictly 1 ecProduct event with eventType detail should be sent when a visitor opens a product details page
  • Multiple ecProduct events with eventType listing are expected on category pages

ecBasketItemTransaction

Transaction events are very important because they report revenue for your website. They are set up in a similar way to basket events except they should only be set up on an order summary page and they should include the 'transaction.id'.

This event collects granular information about individual products contained within a transaction. It enables segmentation based on product preferences, including category, price, color, etc.

  • basket.subtotal.value reports the basket value before the application of taxes, discounts, promotions, shipping costs, etc
  • basket.subtotalIncludingTax.value reports the basket value after the application of taxes, but before any discounts, promotions, shipping costs, etc
  • basket.total.value reports the basket value after the application of taxes, discounts, promotions, shipping costs, etc

Emit ecBasketItemTransaction events for each item in the basket on the order summary page.


Required fields:

  • transaction.id
  • basket.subtotal
  • basket.total
  • product.sku
  • product.productId
  • product.name
  • product.stock
  • product.price
  • product.url
  • product.description
  • product.categories
  • product.images
  • quantity
  • subtotal

Example schema

Field (JS Data Type)

Description

transaction.id (String)

A unique transaction Id

basket.subtotal.value (Number)

The basket subtotal before the application of taxes, discounts, promotions, shipping costs, etc, rounded to 2 decimal places

basket.subtotal.currency (String)

The ISO 4217 currency code, e.g. GBP, USD

basket.subtotalIncludingTax.value (Number)

The basket subtotal, including taxes, but before the application of discounts, promotions, shipping costs, etc, rounded to 2 decimal places

basket.subtotalIncludingTax.currency (String)

The ISO 4217 currency code, e.g. GBP, USD

basket.total.value (Number)

The basket subtotal after the application of taxes, discounts, promotions, shipping costs, etc, rounded to 2 decimal places

basket.total.currency (String)

The ISO 4217 currency code, e.g. GBP, USD

Example JavaScript

var transactionSummary = {
  id: 'aa-44345-hsdsd'
}
var basketSummary = {
  subtotal: {
   currency: 'GBP',
   value: 86,99
  },
  total: {
    currency: 'GBP',
    value: 86,99
  }
}
uv.emit('ecBasketItemTransaction', {
  transaction: transactionSummary,
  basket: basketSummary,
  product: {
    sku: 'sso-099',
    productId: '1209012233',
    name: 'Nike shoes',
    stock: 20,
    price: {
      currency: 'GBP',
      value: 34,50
    },
    url: 'http://www.fashionunion.com/dresses/red-cocktail-dress.html',
    description: 'This red cocktail dress is perfect for any occasion.',
    categories: [
      'Clothing > Sweaters > Short Sleeve Sweaters',
      'New Arrivals > Clothing'
    ],
    images: [
      'http://www.fashionunion.com/dresses/red-cocktail-dress-1.jpg',
      'http://www.fashionunion.com/dresses/red-cocktail-dress-2.jpg'
    ],
  },
  quantity: 1,
  subtotal: {
    currency: 'GBP',
    value: 34,50
  }
})

Setup guidelines

transaction.id
  • Use only valid unicode characters
basket.subtotal
  • Should be emitted when the listed subtotal on the page does not include taxes
  • Emit either basket.subtotal OR basket.subtotalIncludingTax
  • basket.subtotal.value must be rounded to 2 decimal places

Examples of rounding

Good examples:

price: {
  value: 55,
  currency: "USD"
}
price: {
  value: 55.55,
  currency: "USD"
}

Bad examples:

price: {
  value: 55.555,
  currency: "USD"
}

basket.subtotalIncludingTax
  • Should be emitted when the listed subtotal on the page includes taxes
  • Emit either basket.subtotal OR basket.subtotalIncludingTax
  • basket.subtotalIncludingTax.value must be rounded to 2 decimal places. See Examples of rounding for more information
basket.total
  • basket.total.value must be rounded to 2 decimal places. See Examples of rounding for more information
product.productId
product.stock
product.price
  • product.price.value must be rounded to 2 decimal places. See Examples of rounding for more information
product.url
product.categories
product.images
quantity
  • Will be 1 unless there is more than 1 of the same product in the basket subtotal
  • Should be the same as the product price unless there is more than 1 of the same product in the basket

ecBasketTransactionSummary

Emitted on order summary pages, this event collects a summary of information about the transaction. Most importantly, this event is used to count conversions and the associated revenue.

  • basket.subtotal.value reports the basket value before the application of taxes, discounts, promotions, shipping costs, etc
  • basket.subtotalIncludingTax.value reports the basket value after the application of taxes, but before any discounts, promotions, shipping costs, etc
  • basket.total.value reports the basket value after the application of taxes, discounts, promotions, shipping costs, etc

Emit ecBasketTransactionSummary events on the order summary page after ecBasketItemTransaction events.


Required fields:

  • transaction.id
  • basket.subtotal
  • basket.total

Example schemas

Field (JS Data Type)

Description

transaction.id (String)

A unique transaction Id

basket.subtotal.value (Number)

The basket subtotal before the application of taxes, discounts, promotions, shipping costs, etc, rounded to 2 decimal places

basket.subtotal.currency (String)

The ISO 4217 currency code, e.g. GBP, USD

basket.subtotalIncludingTax.value (Number)

The basket subtotal, including taxes, but before the application of discounts, promotions, shipping costs, etc, rounded to 2 decimal places

basket.subtotalIncludingTax.currency (String)

The ISO 4217 currency code, e.g. GBP, USD

basket.total.value (Number)

The basket subtotal after the application of taxes, discounts, promotions, shipping costs, etc, rounded to 2 decimal places

basket.total.currency (String)

The ISO 4217 currency code, e.g. GBP, USD

Example JavaScript

var transactionSummary = {
  id: 'aa-44345-hsdsd'
}
var basketSummary = {
  subtotalIncludingTax: {
    currency: 'GBP',
    value: 68.00
  },
  total: {
    currency: 'GBP',
    value: 75.00
  }
}

Setup guidelines

transaction.id
  • Use only valid unicode characters
basket.subtotal
  • Should be emitted when the listed subtotal on the page includes taxes
  • Emit either basket.subtotal OR basket.subtotalIncludingTax
  • basket.subtotal.value must be rounded to 2 decimal places. See Examples of rounding for more information
basket.subtotalIncludingTax
  • Should be emitted when the listed subtotal on the page includes taxes
  • Emit either basket.subtotal OR basket.subtotalIncludingTax
  • basket.subtotalIncludingTax.value must be rounded to 2 decimal places. See Examples of rounding for more information
basket.total
  • basket.total.value must be rounded to 2 decimal places. See Examples of rounding for more information

Next steps

Once you have completed the setup tasks, you will need to enable Qubit Aura for your property. This will launch Qubit Aura for your mobile visitors, who will be exposed to it depending on your chosen traffic allocation, and execute the data collection process necessary for reporting.

To enable Aura, select Aura from the side menu, switch to the Settings tab, and select Enable Aura.

After enabling Qubit Aura for your property you can make changes to the look and feel of the mobile experience and advanced settings to configure the behavior of the experience. See Configuring Qubit Aura.

In addition, you can use the Featured picks tab to fine-tune product recommendations by adding featured products and rules for product promotions and blacklists. See Curating Aura Recommendations.

Last updated: June 2020
Did you find this article useful?