Advanced Setup Topics

Jolt

Jolt is a lightweight library, deployed as an extension to smartserve.js, to send all QProtocol events that are emitted on your website to Qubit's Data Store.

Jolt enriches QP events with meta data, including:

  • Timestamp
  • Type of event
  • URL
  • View number - the number of views the visitor has had
  • Session number
  • Entrance number
  • Conversion number - if conversion tracking is enabled
  • Lifetime value - if conversion tracking is enabled

Technical details:

  • The library has a size of 23 kb
  • Jolt sends events asynchronously, so will not affect the end-user experience
  • Events that are emitted in a timespan of 500ms will be batched together into one request
  • All event data is compressed with Pako to ensure that the request payload is as small as possible
  • Compression allows a decrease of up to 95% in size for significant proportion of events
  • There is a maximum of 15 events that can be batched into one request. This ensures there are no site lock ups. When exceeding this limit, events are split into multiple requests

Requests

If Jolt is enabled on your site, a 'lookup' request is made per visitor session to Qubit's Data Store. This is to ensure that all the important visitor information is available in the browser. The URL for that request is lookup.qubit.com.

Data inspection

To get a view of the data sent, access window.__qubit.jolt.events, which will contain a list of all the emitted events and their contents.

Cross-domain tracking

Cross-domain tracking works by syncing the cookie state across iframes to a number of different domains. Conventional cross-domain solutions use a third-party cookie to store cross-domain state. However this is very unreliable and doesn't work in all browsers.

To get around third-party cookie limitations, syncing is done directly between the primary website domains that need to be synced, exploiting a rule that allows third-party cookies on domains that have been visited.

To sync cookies between domains, it is necessary to serve an iframe over HTTPS on each linked domain. Our platform uses these iframes to transfer state. Once the iframes are set up, they need to be configured by Qubit.

Setting up iframes

Each domain that is to be linked should have an iframe served that:

  • is HTTPS
  • has a P3P header to allow cookie writing in IE, this can simply be P3P: CP="Unspecified"
  • does not contain any headers such as X-Frame-Options: SAMEORIGIN that will block the iframe running on different domains
  • contains a global variable, safeDomains array, specifying all the domains that will be linked. This is very important for security reasons
  • contains the Qubit script containing the syncing logic https://static.goqubit.com/biscotti-iframe.min.js

For example, to link foo.com and bar.com domains you could serve the following html from https://www.foo.com/xdomain.html and https://www.bar.com/xdomain.html:

<!doctype html>
<html>
  <head>
    <script>
      window.safeDomains = ['bar.com', 'foo.com']
    </script>
    <script src="//static.goqubit.com/biscotti-iframe.min.js"></script>
  </head>
</html>

Caveats

  • Setting up cross domain after data collection has started, will cause some visitor Ids to be merged. This means that a visitor that has 2 visitor Ids across 2 domains will have the data dropped for one of those visitor Ids so that they can be linked.
  • On the first session pageview, syncing cookies will cause experiments to run asynchronously, even if smartserve.js is synchronous. This can cause flicker for landing page experiments.

Check everything is working

Step 1 - Check that the iframes are being loaded

Look at the network panel, using, for example Chrome Devtools, for requests to the specified iframe URLs. If there are no requests, then there is something wrong with the configuration. If this is the case, please reach out to Customer Support at Qubit.

Step 2 - If the iframes have loaded

Navigate to a domain and take note of the context.id sent in any of the events found in window.__qubit.jolt.events, e.g. window.__qubit.jolt.events[0].context.id.

Next navigate to another domain and check that events emitted there match the context.id.

If the context Ids match, you can also check that context.viewNumber increments as you navigate between domains

Example:

In our example, we have two domains, foo.com and bar.com.

Navigate to foo.com and check that the context.viewNumber increments in events in window.__qubit.jolt.events for every pageview. Now open a tab on bar.com and check that context.viewNumber continues from where it was on foo.com.

If the context Ids match and the context.viewNumber increments between domains then your setup is working correctly.

smartserve.js

The smartserve script is a JavaScript bundle hosted on a CDN, which contains all the code that Qubit uses to collect data, compute segments, and serve experiences.

Each time you publish a change to a segment or experience, we republish a new version of smartserve.js that includes your changes.

Minimizing flicker

For clients who intend to run a full-site testing optimization program that includes landing pages, homepage takeovers, and other areas of the site where the user experience is sensitive to perceived user flicker, then we recommend the following setup:

<script src=’//static.goqubit.com/smartserve-1234.js’></script>

Observe the following recommendations:

  • The tag should be loaded at the head of the page
  • The tag should be loaded synchronously
  • The tag should be loaded outside of a tag manager

It is important to understand that this setup comes with a trade-off of increased page latency. Our testing shows that this increased latency is largely imperceptible to the end-user, but this of course depends on the connection used.

Minimizing page load

For customers who place higher importance on page load, we recommend an asynchronous set up:

<script src=’//static.goqubit.com/smartserve-1234.js’ async defer></script>

Observe the following recommendations:

  • The tag should be loaded at the head of the page
  • The tag can be loaded asynchronously
  • The tag can be loaded with in tag manager, although this is not recommended as it could potentially add flicker

In our experience, this is a suitable setup for campaigns that deliver additional messaging to a page such as personalized content, pointers, toggle sliders, and modal boxes.

With this setup, experiments designed to change the content of a landing page or homepage banners, may expose the visitor to small amounts of perceived ‘flicker’.

Qubit cookies

Qubit sets first-party cookies as a reliable way to:

  • Identify individual visitors, and tie them into the data that we collect
  • Target the correct visitor and provide them with a consistent personalized journey
  • Undertake deep analysis of experiences and journeys across a visitor’s lifetime

Refer to the following tables that identifies each of the principal cookies set by Qubit. These are _qubitTracker, qb_permanent, and qb_session. These are set for all customers that have added the smartserve.js script to their site pages.

_qubitTracker

Data Stored

Description

visitorId

Unique Id assigned to the visitor, which never changes

qb_permanent

Data Stored

Description

visitorId

Unique Id assigned to the visitor, which never changes

viewNumber

Increments on a new view

entranceViewNumber

Resets on a new session

sessionNumber

Increments on a new session

entranceNumber

Increments on a new entrance

deliverCloseTime

Sets how long an experience should not be shown for

conversionNumber

Increments on a conversion event

conversionCycleNumber

Increments on a new conversion cycle

lifetimeValue

The visitor’s lifetime value

firstViewTs

First view date for the visitor

lastViewTs

Last view date for the visitor

firstConversionTs

First conversion date for the visitor

lastConversionTs

Last conversion date for the visitor

currency

Visitor’s currency

ipAddress

Visitor’s IP address

Visitor’s geolocation

Including: city, cityCode, country, countryCode, latitude, and longtitude

experienceState

Which experiences the visitor has been served

experienceSegmentations

Which segments the visitor is bucketed to see

qb_session

Data Stored

Description

sessionViewNumber

Resets at the end of a session

visitorIsSynced

Set when a visitor has synchronized this session to ensure accurate session count

eventNumber

Increments when a new event is emitted

experienceState

Which experiences the visitor has been served

iframesInSync

For cross-domain tracking purposes

sessionTs

Timestamp for session start

sessionConversionNumber

The number of conversions in the session

Progressive Web Apps

Qubit technology is enabled via a set of JavaScript files. In the context of Progressive Web Apps, these files can be included in the assets list and will execute as normal.

However any Qubit Experience that make uses of our APIs will not execute when in offline mode. Event data will be collected and sent when the device next has a network connection.

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