# Visii Analytics library

For ease of sending important events to Visii, we provide a va.js script that can be inserted into your page. Once added, calling the track function will send the event to Visii.

Data verification

The library does no client-side checks on the events or fields being sent, so please adhere to the correct format and structure we provide in the documentation.

!function(){var a=window.visii=window.visii||[];a.invoked?window.console&&console.error&&console.error("Visii analytics snippet was added twice."):(a.invoked=!0,a.track=function(){var e=Array.prototype.slice.call(arguments);return a.push(e),a},a.load=function(e){var o=document.createElement("script");o.type="text/javascript",o.async=!0;var i="https://cdn.visii.com/visii.com/va.js";o.src=i;var t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(o,t),a.config=e},a.load({
  organisation:"<organisation>",
  dataset:"<dataset>",
  token:"<token>",
  productSelector: "<dom-string>",
  productIdAttribute: "<dom-attr>",
  userCookie: { anonymous_id: "<anonymous-cookie>", user_id: "<user-id>" },
  vars: {
    page_view_id: "<page_view_id>"
  }
}),a.track("Page Loaded", {page_type:"other"}))}();

Replace in the above script your dataset details:

Field	Type	Required	Value Description
organisation	String	yes	The organisation name
dataset	String	yes	The dataset name
token	String	yes	The dataset API token
productSelector	String	no	The DOMString (opens new window) that identifies a single product on the page. Used for tracking Product Impressions, learn more below. Examples are `.grid-item` or `[data-id]`.
productIdAttribute	String	no	The attribute that contains the product `id` the element specified in `productSelector`. This defaults to a custom data attribute (opens new window) `"data-id"`.
userCookie	Object	no	The cookie name that contains user identifiers: `{anonymous_id:"_anon_cookie",user_id:"_user_cookie"}`
vars	Object	no	Contains parameters needed to group multiple individual requests done while a user interacts with a page.
			The data is used to generate meaningful user metrics.
vars.page_view_id	Number	no	A privacy respecting unique identifier for each user visiting a page.
			It needs to be consistent across all requests done while interacting with the same page.
			Generated by va.js when not supplied. It is required in certain circumstances, see below.

# Tracking Product Impressions

There is a wealth of value to know which products a customer is interested, even those they do not click. These product impressions can be collected automatically with our optimised code as part of va.js. This uses native web APIs (Mutation Observers (opens new window)) rather than scroll events to minimise the CPU load on your customer's machines and handles cross-browser polyfills.

Requirements:

Add product id to all products across your site
These must match those in your dataset
Must be on all pages, even where you do not have a Visii widget
You may use any valid selector
Only 1 product per selector

For example, on a Product Listing Page / Category Page, you have a list of products generated by your CMS. Below is an excerpt of one:

<div class="grid-item">
  <div class="media-card">
    <div class="media-cover">
      <a class="media-image">
        <img class="product-img" src=...>
        ...
</div>
<div class="grid-item">
...

Augment the generator of this page to include the id for that product, in this case we use the data attribute data-id. Ensure only 1 product is contained within the child nodes.

The productSelector would therefore be [data-id] or .grid-item.
The productIdAttribute in the below example would be data-id (which is the default). If you are already using this data attribute, you could set data-visii-id, so the productIdAttribute would be the same.

<div class="grid-item" data-id="product-1">
  <div class="media-card">
    <div class="media-cover">
      <a class="media-image">
        <img class="product-img" src=...>
        ...
</div>
<div class="grid-item" data-id="product-2">
...

# Page View ID

page_view_id is a unique identifier for each user when they visit a page. This will be automatically generated (a timestamp with a random number) if not configured and included across all events originating from this page when using this library.

By being temporary and per page view, it is GDPR compliant as it cannot be used for tracking users nor considered personally identifiable. It is used to link requests to this page visit (and not session).

When requesting recommendations from Vision API please include page_view_id in the vars.

If you generate pages with Visii results from the server-side, generate a page_view_id value to use on the recommendations requests and template the va.js configuration with that value in order to associate following requests with the user page view.

If you use va.js for sending analytics events and client side Javascript for making Vision API requests, configure the va.js snippet with the same page_view_id you use in the recommendation requests. This can be easily done by generating the page_view_id before both including the script and getting the Vision API results, by templating or by storing the value on the global window object.

# Usage

To send analytics to Visii, just call the track function:

Field	Type	Required	Value Description
event-name	String	yes	The event name
data	Object	no	Details associated with the event

window.visii.track("event-name", dataObject);

The track function is using internally the /track endpoint described in the Analytics API.

See below a few examples of using the track function. The dataObject has a predefined structure for Standard Events and a more flexible structure for Custom Events.

window.visii.track("Product Clicked", {
  product_id: "735583523"
});

window.visii.track("Order Completed", {
  currency: "USD",
  tax: 10,
  total_price: 103,
  order_id: "oid293483",
  shipping: 5,
  items: [
    {
      id: "994949",
      price: 22,
      quantity: 1,
      sku: "p29473-C",
      size: "child"
    },
    {
      id: "994949",
      price: 33,
      quantity: 2,
      sku: "p29473-A",
      size: "adult"
    }
  ]
});

← Split Testing