Snowplow Ruby Tracker 0.2.0 released

31 July 2014  •  Fred Blundun

We are pleased to announce the release of the Snowplow Ruby Tracker version 0.2.0. This release brings the Ruby Tracker up to date with the other Snowplow trackers, particularly around support of self-describing custom contexts and unstructured events.

Huge thanks go to Elijah Tabb, a.k.a. ebear, for contributing the updated track_unstruct_event and track_screen_view tracker API methods among other features!

Read on for more information…

  1. New tracker initialization method
  2. Updated format for unstructured events
  3. Updated format for custom contexts
  4. Setting the event ID in the tracker
  5. Other improvements
  6. Getting help

1. New tracker initialization method

The initialization method for the Tracker class has been updated. This is its new signature:

Contract String, Maybe[String], Maybe[String], Bool => Tracker
def initialize(endpoint, namespace=nil, app_id=nil, encode_base64=@@default_encode_base64)

The change is that the context_vendor argument has been removed. This is because contexts are now self-describing JSONs, so sending a context_vendor is redundant.

An example of tracker initialization in version 0.2.0:

require 'snowplow-tracker'

t = SnowplowTracker::Tracker.new('d3rkrsqld9gmqf.cloudfront.net', 'my_tracker_name', 'my_app_id')

2. Updated format for unstructured events

Previously, several arguments were required to build an unstructured event: the name of the event, the JSON describing the event, and the event vendor (the company that developed the event model). Now the signature of track_unstruct_event has been simplified:

Contract @@SelfDescribingJson, Maybe[@@ContextsInput], Maybe[Num] => [Bool, Num]
def track_unstruct_event(event_json, context=nil, tstamp=nil)

A usage example:

t.track_unstruct_event({
  'schema' => 'iglu:com.acme/viewed_product/jsonschema/1-0-0',
  'data' => {
    'product_id' => 'ASO01043',
    'price' => 49.95
  }
})

The event_json argument has two fields: “schema” and “data”. The schema field contains a reference to the JSON schema for the event, and the data field contains describes the event itself. Together they constitute a self-describing JSON.

The tstamp argument is unchanged: it’s an optional timestamp for the event, given in milliseconds since the Unix epoch.

The next section deals with the changes to how the context argument works.

3. Updated format for custom contexts

Custom contexts describe the circumstances around an individual event. In this version, custom contexts must be self-describing JSONs. Each of the Ruby tracker’s trackXXX methods accepts an array of custom contexts as the penultimate optional argument (before the tstamp argument).

An example, attaching two custom contexts to a page view event:

t.track_page_view('http://www.example.com', 'title page', 'http://www.referrer.com', [{
  'schema' => 'iglu:com.acme/viewed_product/jsonschema/1-0-0',
  'data' => {
    'product_id' => 'ASO01043',
    'price' => 49.95
  }
},
{
  'schema' => 'iglu:com.my_company/viewed_product/jsonschema/1-0-0',
  'data' => {
    'user_type' => 'tester'
  }
}])

When tracking an ecommerce transaction, you can attach an array of custom contexts which will be sent with the transaction:

t.track_ecommerce_transaction({
  # map of arguments for the transaction event
  'order_id' => '12345',
  'total_value' => 35,
  'affiliation' => 'my_company',
  'tax_value' => 0,
  'shipping' => 0,
  'city' => 'Phoenix',
  'state' => 'Arizona',
  'country' => 'USA',
  'currency' => 'GBP'
},
[{
  # first item
  'sku' => 'pbz0026',
  'price' => 20,
  'quantity' => 1,
  # context for first item
  'context' => [{
    'schema' => 'iglu:com.my_company/promotions/jsonschema/1-0-0',
    'data' => {
      'promotion_name' => 'half price'
      'promotion_duration' => 24
    }
  }]
},
{
  # second item
  'sku' => 'pbz0038',
  'price' => 15,
  'quantity' => 1,
  'name' => 'crystals',
  'category' => 'magic'
}],
[{
  # context for overall transaction
  'schema' => 'iglu:com.my_company/page_type/jsonschema/1-0-0',
  'data' => {
    'type' => 'test_page'
  }
}])

Under the hood, this complicated example will send three events: one transaction event and two transaction item events. The transaction event has an array containing one “page_type” custom context attached. The first transaction item event has an array containing one “promotions” custom context attached.

4. Setting the event ID in the tracker

We are phasing out the old “tid” transaction ID field because, as a random 6-digit number, it wasn’t sufficiently unique. It has been replaced with an “eid” field containing a UUID. If set, this “eid” UUID will be used as the “event_id” for this event.

This is hugely valuable if the Snowplow Enrichment process is running in an at-least-once stream processing system, because you can use the tracker-set event ID to identify duplicates downstream of the Enrichment.

5. Other improvements

We have also:

  • Updated track_screen_view to send a valid self-describing JSON - thanks @ebear! #21
  • Fixed broken links in the README #27
  • Fixed the coveralls.io button in the Github repository #17

6. Getting help

Useful links:

If you have an idea for a new feature or want help getting things set up, please get in touch. This is only the second release of the Ruby Tracker, so we’re keen to hear people’s opinions. And raise an issue if you spot any bugs!