Event enrichment

This is for:

Developer

In this article, we’ll take a look at Jolt and how it enriches QProtocol events emitted on your site during as part of the data collection process.

How do we enrich events?

Jolt is a lightweight library, deployed as an extension to smartserve.js, that listens for and sends all QProtocol events emitted on your website to Qubit’s Data Store.

As part of this process, Jolt enriches each event with visitor information, making it available in the browser for querying. It also sends a copy to our backend, via our Event Validation API - this ensures that each event conforms to our AVRO-based schema specification.

For each validated event, we also enlist a server-side process to add further enrichment, including:

  • Referrer categorization

  • Timezone conversion

  • Currency conversion

Let’s take a look at how an event is transformed as it passes through this pipeline, taking a product event such as ecProduct as an example.

Process

Event emission

The basic event emitted on a product page may be similar to this example, taken from our ecommerce setup guide:

uv.emit('ecProduct', {
  eventType: 'detail',
  product: {
    sku: 'sso-099',
    productId: '1209012233',
    name: 'Nike shoes',
    stock: 20,
    color: 'red',
    size: '12',
    price: {
      currency: 'GBP',
      value: 34
    },
    originalPrice:{
      currency: 'GBP',
      value: 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'
    ],
    manufacturer: 'XYZ Dresses'
  }
})

Although the event tells us about the product itself, at this stage, we don’t have any information about the user that visited the page - their session number, lifetime value, some way of identifying the unique user; this information is of course key to our efforts to understand users and their behavior on a site.

This is where Jolt is used to enrich the event.

Meta and context enrichment

To the above event, Jolt adds meta and context data:

Meta data

"meta": {
   "type": "ecProduct",
   "id": "02ctseef42s-0jnlmjnd4-2bpl5iw",
   "ts": 1540292769538,
   "seq": 5,
   "url": "http://retail-demo-uk.qubit.com/#qb_opts=preview,bypass_segments&qb_experiences=787837&qubit_explorer",
   "batchTs": 1540292769538,
   "trackingId": "demo_v2_fashion",
   "source": "jolt@7.49.0",
   "bundleId": "2018-10-23T08:47:20@c505922@latest@2018-10-23T11:05:52"
 }

Let’s break down this data:

Field (JS Data Type) Description

url (String)

The current page URL the event was emitted from

trackingId (String)

The tracking Id for your property

batchTs (Number)

The timestamp for when the batch of events was sent to Qubit

type (String)

The event type that was enriched by Jolt

source (String)

The version of Jolt deployed on your site

id (String)

Random Id for the emitted event

bundleId (String)

The version and build of Smartserve

seq (Number)

A sequence that reports the number of events emitted by the visitor globally by device and site

ts (Number)

The client-side timestamp for when the event was emitted - will always be less than batchTs

Context data

Field (JS Data Type) Description

viewTs (Number)

A timestamp for the most recent view event

sessionViewNumber (Number)

The session number for the visitor.Defined as any sequence of view events with less than 30 minutes between each view

entranceViewNumber (Number)

The entrance view number for the visitor.Defined as any sequence of view events where the first page comes from an external link, entered URL, or bookmark and where all subsequent pageviews are triggered by a selection within the website

lifetimeValue.value (Number)

The total amount transacted by the visitor over their lifetime - updated at the beginning of the next session

lifetimeValue.currency (String)

The ISO 4217 currency code for the user (for example, GBP, USD)

sample (String)

A randomly generated hash of the context Id used for sampling

timezoneOffset (Number)

The timezone offset of the visitor in minutes from UTC

viewNumber (Number)

The number of view events across the user’s lifetime

sessionTs (Number)

Timestamp for when the session was initiated

entranceTs (Number)

Timestamp for when the entrance was initiated

conversionCycleNumber (Number)

The number of conversion cycles the visitor has had across their lifetime. The conversionCycleNumber increments only on the session following a session with one or more conversions

id (String)

Equivalent of visitor Id and cookie Id that is randomly assigned to each visitor to identify them on your site - device specific

sessionNumber (Number)

The number of sessions the visitor has had across their lifetime

entranceNumber (Number)

The number of entrances the visitor has had across their lifetime

conversionNumber (Number)

The number of conversions the visitor has made during their lifetime - updated on the next view event after a conversion