A guide to unstructured events in Snowplow 0.8.3
Earlier today we announced the release of Snowplow 0.8.3, which updated our JavaScript Tracker to add the ability to send custom unstructured events to a Snowplow collector with trackUnstructEvent()
.
In our earlier blog post we briefly introduced the capabilities of trackUnstructEvent
with some example code. In this blog post, we will take a detailed look at Snowplow’s custom unstructured events functionality, so you can understand how best to send unstructured events to Snowplow.
Understanding the unstructured event format is important because our Enrichment process does not yet extract unstructured events, so you will not get any feedback yet from the ETL as to whether you are tracking them correctly. (Nor do we have validation for unstructured event properties in our JavaScript Tracker yet.)
In the rest of this post, then, we will cover:
1. Basic usage
Tracking an unstructured event with the JavaScript Tracker is very straightforward - use the trackUnstructEvent(name, properties)
function:
name
is the name of the unstructured event. This is case-sensitive; spaces etc are allowedproperties
is a JavaScript object
Here is an example:
_snaq.push(['trackUnstructEvent', 'Viewed Product', { product_id: 'ASO01043', category: 'Dresses', brand: 'ACME', returning: true, price: 49.95, sizes: ['xs', 's', 'l', 'xl', 'xxl'], available_since$dt: new Date(2013,3,7) } <span class="p">]);
Every call to trackUnstructEvent
has the same structure - the complexity comes from knowing how to structure the properties
JavaScript object. We will discuss this next:
2. The 'properties' JavaScript object
The properties
JavaScript consists of a set of individual name: value
properties.
The structure must be flat - in other words, properties cannot be nested. Continuing with the exampe code above, this means that the following is not allowed:
{ category: { primary: 'Womenswear', secondary: 'Dresses'}, // NOT allowed }
The properties
JavaScript object supports a wide range of datatypes - see below for details.
3. Supported datatypes
Snowplow unstructured events support a relatively rich set of datatypes. Because these datatypes do not always map directly onto JavaScript datatypes, we have introduced some “type suffixes” for the JavaScript property names, to tell Snowplow what Snowplow datatype we want the JavaScript data to map onto.
Our datatypes, then, are as follows:
Snowplow datatype Description JavaScript datatype Type suffix(es) Supports array? Null Absence of a value Null - No String String of characters String - Yes Boolean True or false Boolean - Yes Integer Number without decimal Number $int
Yes Floating point Number with decimal Number $flt
Yes Geo-coordinates Longitude and latitude [Number, Number] $geo
Yes Date Date and time (ms precision) Number $dt
, $tm, $tms
Yes Array Array of values [x, y, z] - -
Let’s go through each of these in turn, providing some examples as we go:
Null
Tracking a Null value for a given field is straightforward:
{ returns_id: null }
String
Tracking a String is easy:
{ product_id: 'ASO01043' // Or "ASO01043" }
Boolean
Tracking a Boolean is also straightforward:
{ trial: true }
Integer
To track an Integer, use a JavaScript Number but add a type suffix like so:
{ in_stock$int: 23 }
Warning: if you do not add the $int
type suffix, Snowplow will assume you are tracking a Floating point number.
Floating point
To track a Floating point number, use a JavaScript Number; adding a type suffix is optional:
{ price$flt: 4.99, sales_tax: 49.99 // Same as $sales_tax:$flt }
Geo-coordinates
Tracking a pair of Geographic coordinates is done like so:
{ check_in$geo: [40.11041, -88.21337] // Lat, long }
Please note that the datatype takes the format latitude followed by longitude. That is the same order used by services such as Google Maps.
Warning: if you do not add the $geo
type suffix, then the value will be incorrectly interpreted by Snowplow as an Array of Floating points.
Date
Snowplow Dates include the date and the time, with milliseconds precision. There are three type suffixes supported for tracking a Date:
$dt
- the Number of days since the epoch$tm
- the Number of seconds since the epoch$tms
- the Number of milliseconds since the epoch. This is the default for JavaScript Dates if no type suffix supplied
You can track a date by adding either a JavaScript Number or JavaScript Date to your properties
object. The following are all valid dates:
{ birthday$dt: new Date(1980,11,10), // Sent to Snowplow as birthday$dt: 3996 birthday2$dt: 3996, // ^ Same as above registered$tm: new Date(2013,05,13,14,20,10), // Sent to Snowplow as registered$tm: 1371129610 registered2$tm: 1371129610, // Same as above last_action$tms: 1368454114215, // Accurate to milliseconds last_action2: new Date() // Sent to Snowplow as last_action2$tms: 1368454114215 }
Note that the type prefix only indicates how the JavaScript Number sent to Snowplow is interpreted - all Snowplow Dates are stored to milliseconds precision (whether or not they include that level of precision).
Two warnings:
- If you specify a JavaScript Number but do not add a valid Date suffix (
$dt
,$tm
or$tms
), then the value will be incorrectly interpreted by Snowplow as a Number, not a Date - If you specify a JavaScript Number but add the wrong Date suffix, then the Date will be incorrectly interpreted by Snowplow, for example:
{ last_ping$dt: 1371129610 // Should have been $tm. Snowplow will interpret this as the year 3756521449 }
Arrays
You can track an Array of values of any data type other than Null.
Arrays must be homogeneous - in other words, all values within the Array must be of the same datatype. This means that the following is not allowed:
{ sizes: ['xs', 28, 'l', 38, 'xxl'] // NOT allowed }
By contrast, the following are all allowed:
{ sizes: ['xs', 's', 'l', 'xl', 'xxl'], session_starts$tm: [1371129610, 1064329730, 1341127611], check_ins$geo: [[-88.21337, 40.11041], [-78.81557, 30.22047]] }
4. Getting help
As always, if you do run into any issues or don’t understand any of the above guide, please do get in touch with us via the usual channels.
And if you have any ideas or feedback for Snowplow’ custom unstructured events, do please share them, either in the comments below or through the usual channels.