Skip to main content

Getting started

Installation​

The Snowplow Ruby Tracker is compatible with Ruby 2.1+, including 3.0+. 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​

Find the Ruby tracker code here, and the API documentation here.

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

The Ruby tracker version 0.7.0 had some breaking changes, notably the addition of keyword arguments. 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.

Note that the Rails demo has both the Ruby and JavaScript trackers implemented. This combination of client- and server-side tracking can be highly effective and powerful. For example, you can discover how much effect adblockers are having on your tracking, by comparing the amount of client-side and server-side page view events you collect. It also allows you to track events in the most appropriate way for the event type. Check out this blog post for more discussion about tracking client- and server-side.

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.

Initializing a tracker instance:

require 'snowplow-tracker'

emitter = SnowplowTracker::Emitter.new(endpoint: 'collector.example.com')
tracker = SnowplowTracker::Tracker.new(emitters: emitter)
# or
tracker = SnowplowTracker::Tracker.new(emitters: [emitter])

This Tracker will send events via GET to http://collector.example.com/i. To use other settings, such as POST or HTTPS, see "Configuring how events are sent".

caution

Do not include the protocol (HTTP or HTTPS) in your collector address. It will be added automatically.

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 set_subject.

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:

require 'snowplow-tracker'

SnowplowTracker::Tracker.new(emitters: SnowplowTracker::Emitter.new(endpoint: 'collector.example.com'),
                             subject: SnowplowTracker::Subject.new,
                             namespace: 'tracker_no_encode',
                             app_id: 'rails_main',
                             encode_base64: false
                             )

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 recommend using Snowplow Micro for testing and debugging — you can even use it for automated tests.

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.