Collecting data with Trackers and Webhooks

  1. Home
  2. Docs
  3. Collecting data with Trackers and Webhooks
  4. Trackers – collecting data from your own applications
  5. Ruby Tracker
  6. Getting started

Getting started

Installation

The Snowplow Ruby Tracker is compatible with Ruby 2.1+, including 3.0+. To install it locally:

$ gem install snowplow-tracker
Code language: Bash (bash)

To add the Snowplow Tracker to your Ruby app or gem, add this line to your Gemfile:

gem 'snowplow-tracker', '~> 0.8.0'
Code language: Ruby (ruby)

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

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. See “Configuring how events are sent for more information about configuring Emitters.

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])
Code language: Ruby (ruby)
Using Ruby tracker <0.7.0? Expand this
require 'snowplow-tracker' emitter = SnowplowTracker::Emitter.new('collector.example.com') tracker = SnowplowTracker::Tracker.new(emitter) # or tracker = SnowplowTracker::Tracker.new([emitter])
Code language: PHP (php)

This Tracker will send events via GET to http://collector.example.com/i.

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)
Code language: Ruby (ruby)
Using Ruby tracker <0.7.0? Expand this
require 'snowplow-tracker' SnowplowTracker::Tracker.new(SnowplowTracker::Emitter.new('collector.example.com'), SnowplowTracker::Subject.new, 'tracker_no_encode', 'rails_main', false)
Code language: Ruby (ruby)

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.

If you’d like to learn more about Snowplow BDP you can book a demo with our team, or if you’d prefer, you can try Snowplow technology for yourself quickly and easily.