Script Implementation Guide

To get CUBED Attribution up and running on your website, you will need the following tags:

  1. The base tag, which must fire on every page.
  2. The page specific scripts.
  3. The fire tag.

Note that in order for CUBED Attribution to work, the base tag must be fired first, and the "fire tag" must be last.

Table of Contents




Cookies

Overview

The Cubed tag will need to drop a couple of cookies to track Visitor and Session information. No identifiable information is stored in these.
When our tag talks to the Cubed server, we return a unique token for Visitor, and another unique token for Session.
All our cookies are categorised as "analytical". Please see below.

Information

Name Category Description Expires
vscr_vid Analytical Cookie that contains the Visitor token. 6 months or when cookies are deleted.
vscr_sid Analytical Cookie that contains the Visitor's Session token. 30 minutes or when browser is closed.
vscr_reqid Analytical Cookie that attempts to track a Visitor across different tabs. This is a legacy feature and is slowly being removed from our tag/system. 30 minutes or when browser is closed.

The preferred method for tracking visitors involves the use of a company specific first party domain for setting cookies and collecting the Cubed data; this approach is compliant with ITP based browsers and allows the maximum coverage for cookie setting and data collection. For this functionality, clients will need to work with their account managers to enable to process to begin. The process has the following requirements:

  1. You will need to nominate a data collection domain. For example, you may wish to collect data to cubed.mydomain.com. Note that the top level domain mydomain.com must match the top level domain of the website being tracked.
  2. You will need to create a CNAME record within your domain name server that points the created domain to the Cubed data collectors - details of this requirement will be provided by your account manager.
  3. You will need to provide SSL certificates to allow the data collection to be secure at the Cubed data collectors. Cubed can provide a managed certificate service in most instances if required.

Once this process has been completed, you should then refer to the Set Server section below in order to use the new domain names.




Step 1 - Add the Base CUBED Attribution Script

The Base Tag

This code should be placed on all pages within website, and must have 'account_token' replaced by the relevant account token.

<script>
    (function() { 
        var script = document.createElement("script"); 
        script.type = "text/javascript"; 
        script.async = true; 
        script.src = "//d2hkbi3gan6yg6.cloudfront.net/visscore.tag.min.js"; 
        var s = document.getElementsByTagName("script")[0]; 
        s.parentNode.insertBefore(script, s); 
    })(); 
    var vscr = window.vscr || []; 
    vscr.push(["setAccount", "<account token>"]); 
</script>

Contact support if you don't have an account token.

Set Server

This allows the tag to be fired to a different URL. By default our tag fires to the server: "data.withcubed.com" It is possible to setup Data Collection Servers (DCS) at any URL. Use this function if you wish to change that.

Syntax for setting the server:

vscr.push(["setServer" , "Server Address"])

Note

Do not set this unless the server name has been created.

First Party Cookies

In order to allow Cubed the ability to store cookies in a first-party manner, we may request a client setup a subdomain to point at our Data Collection Servers (data.withcubed.com). This means we can fire our tag at (for example) cubed.client.com, which will then process the data at data.withcubed.com, but be allowed to set cookies on client.com. For this to work the tag needs setServer called, and setCookiesOnServer to be true. Both functions will need to be called every time the tag is loaded - along with Set Account.

Syntax for setting the server and cookie functionality:

vscr.push(["setServer" , "cubed.client.com"]) 
vscr.push(["setCookiesOnServer" , true])

Note

Do not set this unless the server name has been created.

End Points

To allow tracking across different domains, we offer the ability to append both Visitor and Visit tokens to a site's anchor links. For example if you have the Cubed tag on both www.mywebsite.com and www.mysite.co.uk, you may want to track people going across. When you add an End Point, our tag attempts to find all matching anchor links with this URL in their href and it will append our query parameter "ydat" and add the visitor and visit tokens.

Syntax for setting End Points:

vscr.push(["addEndPoint" , "My website URL"])

Example:

If you wanted to track a visitor going from www.mywebsite.com to www.mysite.co.uk, in your mywebsite.com tag you would add the End Point "mysite.co.uk". See below. Now any link that points to mysite.co.uk will have ydat=visitorIDvisitID as a query parameter.

/* tag loaded on www.mywebsite.com */
vscr.push(["addEndPoint" , "mysite.co.uk"])

Forward Parameters

In addition to capturing the standard referrer information, the CUBED Attribution product supports the capture of landing page URL parameters which can then be used to classify marketing channels. As an example, it may be a requirement to capture the utm_campaign parameter so that it can be used to further configure the referrer channels.

The syntax for using forward parameters is:

vscr.push(["addForwardParam" , "Parameter Name"])

In order to capture multiple forward parameters, you will need to repeat this step for each parameter you wish to capture, for example:

vscr.push(["addForwardParam", "utm_campaign"]) 
vscr.push(["addForwardParam", "utm_channel"])




Step 2 - Adding Page-Specific Scripts

In general, adding page specific parameters requires you to push the parameters to the CUBED Attribution request using the general syntax:

[ command_name, values ]

Firing Events

The most used page-specific parameter is 'addEvent', which allows you to capture events for use within the CUBED Attribution interface. Please note that these events must have been preconfigured in the CUBED Attribution interface before they can be captured.

Event Name - Mandatory

The most basic syntax for addEvent is as follows, and must be included in order for an event to be captured:

vscr.push(["addEvent", {name: "Event Name" }])

In here, you would change "Event Name" to the name of the event that you wish to fire.

You are also able to capture further information about the event; as well as the event name itself, you can also capture revenue, transaction ID, and specific item details.

You can name events anything you like, but they must be set up in the CUBED Attribution interface with names that match exactly before you begin capturing data. An event can be applied to multiple products, and a product must have a sale event defined in the CUBED Attribution interface.

Revenue - Optional

This parameter is optional, and is used to capture the revenue attached to an event.

vscr.push(["addEvent", {name: "Event Name", revenue: "1500"}])

If used, you must provide a valid number with an optional two decimal places. This value can be either a number or a string. You must remove all commas and currency symbols before pushing the event.

Examples:

Transaction ID - Optional

This parameter is used to capture a unique transaction ID for any event.

vscr.push(["addEvent", {name: "Event Name", revenue: "1500", transactionId: "abcdef123"}])

Wherever possible, a transaction ID should be passed up, and must be passed up as a string.

Examples:

Firing Events With Details

Item Details - Optional

If you wish to capture the details of a particular item when firing the event, you will need to use the details parameter. This is an array of objects, where each object is a particular item.

You are able to pass up the following parameters for each object:

Of the parameters above, only Name is mandatory.

The script to capture details with an event is as follows:

vscr.push(["addEvent", {
        name:"Event Name",
        revenue: "Revenue",
        transactionId: "Transaction ID",
        details:[{
            name: "Item1 Name",
            sku: "Item1 SKU",
            quantity: "10",
            cost: "100.50"
        }]  
    }
])

Also with multiple details:

vscr.push(["addEvent", {
    name:"Event Name",
    revenue: "Revenue",
    transactionId: "Transaction ID",
    details: [{
            name: "Item1 Name",
            sku: "Item1 SKU",
            quantity: "10",
            cost: "100.50"
        },
        {
            name: "Item2 Name",
            sku: "Item2 SKU",
            quantity: "5",
            cost: "600.00"
        }]
    }
])

Both name and SKU must be captured as a string; quantity and cost can be captured as either string or number, but as with revenue, all commas and currency symbols must be removed before pushing the event.

Discount Details - Optional

If you wish to capture the discount codes when firing an event, you will need to use the discounts parameter. This is an array of objects, where each object is a particular discount item.

You are able to pass up the following parameters for each object:

Of the parameters above, only Name is mandatory.
Code defaults to a blank string ''.
Price defaults to 0.0.
Currency defaults to 'GBP'.

The script to capture an event with discount details:

vscr.push(["addEvent", {
        name:"Event Name",
        revenue: "Revenue",
        transactionId: "Transaction ID",
        discounts:[{
            name: "My Discount Code",
            code: "discount-10ABC",
            price: -10,
            currency: "GBP"
        }]  
    }
])

Also with multiple details:

vscr.push(["addEvent", {
    name:"Event Name",
    revenue: "Revenue",
    transactionId: "Transaction ID",
    discounts: [{
            name: "My Discount Code",
            code: "discount-10ABC",
            price: -100,
            currency: "GBP"
        },
        {
            name: "Another Voucher Code",
            code: "2015-voucher-123",
            price: -10.50,
        }]
    }
])

Both name and code must be captured as a string; price can be captured as either string or number, but as with revenue, all commas and currency symbols must be removed before pushing the event with discounts.

Shipping Details - Optional

If you wish to capture the shipping details for an event, you will need to use the shippings parameter. This is an array of objects, where each object is a particular shipping item detail.

You are able to pass up the following parameters for each object:

Of the parameters above, only Name is mandatory.
Code defaults to a blank string ''.
Price defaults to 0.0.
Currency defaults to 'GBP'.

The script to capture an event with shipping details:

vscr.push(["addEvent", {
        name:"Event Name",
        revenue: "Revenue",
        transactionId: "Transaction ID",
        shippings:[{
            name: "Shipping Global",
            code: "shipping-2000",
            price: 30,
            currency: "GBP"
        }]  
    }
])

Also with multiple details:

vscr.push(["addEvent", {
    name:"Event Name",
    revenue: "Revenue",
    transactionId: "Transaction ID",
    shippings: [{
            name: "Shipping Global",
            code: "shipping-2000",
            price: 30,
            currency: "GBP"
        },
        {
            name: "Shipping Extra",
            code: "extra-2018",
            price: 15.50,
        }]
    }
])

Both name and code must be captured as a string; price can be captured as either string or number, but as with revenue, all commas and currency symbols must be removed before pushing the event with discounts.

Firing Labels

As well as capturing events, you are also able to capture labels.

Labels are very versatile and can be used to capture a wide variety of data. As an example, you can use labels to capture a visitor's gender and date of birth, as well as their non-event related activities, such as their choices on a product configuration page.

You must define the label type, the label's key, and the label's value.

Label Types

There are 5 label types, and the type must be defined in the label push. The label type commands are as follows:

The syntax for capturing labels is as follows:

vscr.push(["Label Type", "Key", "Value"])

For example:

vscr.push(["addIntLabel", "my_intLabel1", "42"]) 
vscr.push(["addIntLabel", " my_intLabel2", 42])  
vscr.push(["addFloatLabel", " my_floatLabel1", 123.45]) 
vscr.push(["addFloatLabel", " my_floatLabel2", "123.45"])  
vscr.push(["addStringLabel", " my_stringLabel", "str value"])  
vscr.push(["addDatetimeLabel", " my_dateLabel1", "2015-11-16"]) 
vscr.push(["addDatetimeLabel", " my_dateLabel2", "2015-11-16T22:23:48+00:00"])
vscr.push(["addBoolLabel", "my_boolLabel", "true"])

Firing Sync IDs

The CUBED Attribution product allows the capture of Sync IDs to join customer records across multiple devices and platforms. These sync IDs are stored in a hashed format, but are passed in the JavaScript call in standard format. You can use any unique identifier as a Sync ID, such as telephone number or email address.

The standard syntax for capturing sync IDs is as follows:

vscr.push(["addSyncId", "Sync ID Value"])

For example, if you are using email address as a Sync ID, the call would appear as:

vscr.push(["addSyncId", "support@withcubed.com"])

In the same way as our other tag calls, you can fire multiple Sync IDs in a single hit by calling the relevant push function twice before firing the tag. For example:

vscr.push(["addSyncId", "support@withcubed.com"]) 
vscr.push(["addSyncId", "vs34541122"])

Firing a Customer ID

When capturing visitor data in the Cubed platform, you may want to join external visitor data to Cubed data. This can be done by passing a Customer ID in to the tag. This will allow you to link any external information you have associated with that Visitor with Cubed data, at a later date.

Syntax for passing the Customer Id:

vscr.push(["addCustomerId", "idABC_12345"])




Step 3 - Firing the CUBED Attribution Tag

Once all parameters have been added, it is essential to fire the CUBED Attribution hit. This command is fired as below:

vscr.push(["fire"])

Note that this should always be the last call in the tag. Anything pushed after the fire tag will not be collected in that hit, and will require another fire in order to be collected - this is important to remember for any parameters that are not fired immediately, for example with on click events.

Examples

Standard page, no specific parameters

vscr.push(["fire"])

Single Event

vscr.push(["addEvent", {name: "Event Name"}]) 
vscr.push(["fire"])

Single Event with Revenue, Transaction ID, and Multiple Item Details

vscr.push(["addEvent", 
    {
        name: "Event Name",
        revenue: "Revenue",
        transactionId: "Transaction ID",
        details:[{
            name: "Item1 Name",
            sku: "Item1 SKU",
            quantity: "10",
            cost: "100.50"
        },
        {
            name: "Item2 Name",
            sku: "Item2 SKU",
            quantity: "5",
            cost: "600.00"
        }]  
    }
])
vscr.push(["fire"])

Multiple Sync IDs and Labels

vscr.push(["addStringLabel", " Gender", "Male"]) 
vscr.push(["addDatetimeLabel", " DOB", "1980-12-31"]) 
vscr.push(["addSyncId", "support@withcubed.com"]) 
vscr.push(["addSyncId", "vs34541122"]) 
vscr.push(["fire"])

Step 4 - Override Functions

Override Overview

The Cubed tag has a couple of functions that can be overidden to implement custom clientside logic, realtive to the current state of the Cubed vscr object.
These should be added with the base tag, after setAccount has been called.

Pre Tag Fire

This function is to allow you to set any clientside logic based on the state of vscr object before the tag is fired to our server. The state objects hold properties such as visitor token and the visit token, see table below for more details.
This function is not intended as a way to manipulate the vscr object or its state. It is provided as a way of using the current state of the tag to perform other actions on the page.

Variable Definition
accountId Account token used by server.
customerId The set current Customer Id.
events Array of Events for this tag fire.
forwardParams Array of Forward Params used to append landing page query params to document.referrer.
labels Array of Labels.
log Array of logs reflecting what the tag has done.
referrer Where the visit has come from.
server The domain this tag will fire to.
syncIds Array of syncIds as set in the tag.
visitId The token used in the Cubed database for this Visit's data.
visitorId The token used in the Cubed database for this Visitor's data.
vscr.push(["onPreFire", function(state) {

}]);

Note

Do NOT use this function to set/modify state object variables, please use the relative functions mentioned above.

Tag Fire Complete

This function is called once the page has recieved a response from our Data Collection Server. The function is called with the Visitor Token, and CASK (Cubed Authentication Server Key).
These can be used together to make requests to our external APIs, such as the VisScore Service.

vscr.push(["onTagComplete", function(vid, cask) {

}]);

Note

The CASK is relative to the Visitor Token, and can only be used with that Id to obtain information.

Example (using jQuery):

vscr.push(["onTagComplete", function(accountToken, visitorId, sessionId, cask) {
    jQuery.ajax({
        url: 'https://api.withcubed.com/visscore',
        type: 'get',
        data: {
            'aid': accountToken
            'vid': visitorId,
            'cask': cask,
        },
        success: function(data) {

        },
    })
}]);