The Snowplow Ruby Tracker is compatible with Ruby 2.1+, including 3.0+. To install it locally:
$ gem install snowplow-tracker
To add the Snowplow Tracker to your Ruby app or gem, add this line to your Gemfile:
gem 'snowplow-tracker', '~> 0.8.0'
To make the Snowplow Ruby Tracker work with as many different Ruby programs as possible, we have tried to keep external dependencies to a minimum. There are only two external dependencies currently, both of which are for development of the gem itself: rspec and webmock.
Introduction to the tracker code
The main class of the Ruby tracker is the Tracker class. Trackers provide methods for tracking events, such as
track_page_view. The Tracker creates an appropriate event payload out of the provided event properties. This payload is passed to one or more Emitters for sending to the event collector.
Data about users, and which platform (e.g. server-side app or mobile) the event occurred on, are managed by Subject objects. A Subject can be added to each event, and Trackers always have an associated Subject. Other information can be added to events using Page, DeviceTimestamp or TrueTimestamp objects, as well as via event context. Event context is added via SelfDescribingJson objects.
Note that the Ruby tracker version 0.7.0 had some breaking changes, specifically the addition of keyword arguments. If you are using version <0.7.0, look out for the dropdowns under code examples on these pages for the old API. Check out the tracker changelog here.
Tracking design and initialization
Designing how and what to track in your app is an important decision. Check out our docs about tracking design here.
We suggest implementing the Ruby tracker as a Singleton global object. This pattern is demonstrated in our Ruby on Rails example app. Structuring your code in this way avoids wasting bandwidth or processing on reinitializing Trackers and Emitters for every page load or event sent.
The Tracker must be initialized with an Emitter or the subclass AsyncEmitter (or an array of Emitters/AsyncEmitters). The only required argument for an Emitter/AsyncEmitter is the endpoint, i.e. the address of the event collector. See "Configuring how events are sent" for more information about configuring Emitters.
Initializing a tracker instance:
emitter = SnowplowTracker::Emitter.new(endpoint: 'collector.example.com')
tracker = SnowplowTracker::Tracker.new(emitters: emitter)
tracker = SnowplowTracker::Tracker.new(emitters: [emitter])
emitter = SnowplowTracker::Emitter.new('collector.example.com')
tracker = SnowplowTracker::Tracker.new(emitter)
tracker = SnowplowTracker::Tracker.new([emitter])
This Tracker will send events via GET to
At initialization, two Tracker parameters can be set which will be added to all events. The first is the Tracker
namespace. This is especially useful to distinguish between events from different Trackers, if more than one is being used. The second user-set Tracker property is the
app_id. This is the unique identifier for the site or application, and is particularly useful for distinguishing between events when Snowplow tracking has been implemented in multiple apps.
A Tracker is always associated with a Subject. It will be generated automatically if one is not provided during initialization. It can be swapped out later for another Subject using
The final initialization parameter is a setting for the base64-encoding of any JSONs in the event payload. The default is for JSONs to be encoded. Once the Tracker has been instantiated, it is not possible to change this setting.
Initializing a tracker instance with all possible settings used:
SnowplowTracker::Tracker.new(emitters: SnowplowTracker::Emitter.new(endpoint: 'collector.example.com'),
You can create as many Tracker instances as you like within your app; each one is completely sandboxed. For example, you may wish to send certain events to a different collector endpoint (using a different Emitter), or with a different JSON base64-encoding choice. Make sure you set different Tracker namespaces when using multiple instances.
Testing your tracking
Testing that your event tracking is properly configured can be as important as testing the other aspects of your app. It confirms that you are generating the events you expect.
We provide two types of pipeline for testing and debugging. Snowplow Mini is especially useful in manual schema and pipeline testing. Snowplow Micro is a minimal pipeline designed to be used as part of your app's automated test suite.
Check out our Ruby tracker Rails demo and Snowplow Micro examples repo for two examples of automated webapp testing using Snowplow Micro and the testing framework Cypress. Any end-to-end testing framework can be used.