Tracking specific events

Page contents show page contents

Snowplow has been built to enable you to track a wide range of events that occur when users interact with your websites and apps. We are constantly growing the range of functions available in order to capture that data more richly.

Tracking methods supported by the Ruby Tracker at a glance:

Function	Description
`track_page_view`	Track and record views of web pages.
`track_ecommerce_transaction`	Track an ecommerce transaction
`track_screen_view`	Track the user viewing a screen within the application
`track_struct_event`	Track a Snowplow custom structured event
`track_self_describing_event`	Track a Snowplow custom unstructured event

Common

All events are tracked with specific methods on the tracker instance, of the form track_XXX(), where XXX is the name of the event to track.

All tracker methods return the tracker instance, and so are chainable.

Argument validation

Each track_XXX method expects arguments of a certain type. The types are validated using the Ruby Contracts library. If a check fails, a runtime error is thrown. The section for each track_XXX method specifies the expected argument types for that method.

Optional context argument

Each track_XXX method has context as its penultimate optional parameter. This is for an optional non-empty array of self-describing custom context JSONs attached to the event. Each element of the context argument should be a SelfDescribingJson with two fields: the “schema”, pointing to the JSON schema against which the context will be validated, and the “data”, containing the context data itself. The “data” field should contain a flat hash of key-value pairs.

Important:

Even if only one custom context is being attached to an event, it still needs to be wrapped in an array.

For example, an array containing two custom contexts relating to the event of a movie poster being viewed:

# Array of contexts
[
  # First context
  SnowplowTracker::SelfDescribingJson.new(
    'iglu:com.my_company/movie_poster/jsonschema/1-0-0',
    {
      'movie_name' => 'Solaris',
      'poster_country' => 'JP',
      'poster_year$dt' => new Date(1978, 1, 1)
    }
  ),

  # Second context
  SnowplowTracker::SelfDescribingJson.new(
    'iglu:com.my_company/customer/jsonschema/1-0-0',
    {
      'p_buy' => 0.23,
      'segment' => 'young adult'
    }
  )
]
Code language: PHP (php)

The keys of a context hash can be either strings or Ruby symbols.

For more on how to use custom contexts, see the blog post which introduced them.

Optional timestamp argument

After the optional context argument, each track_XXX method supports an optional timestamp as its final argument. This allows you to manually override the timestamp attached to this event. If you do not pass this timestamp in as an argument, then the Ruby Tracker will use the current time to be the timestamp for the event. Timestamp is counted in milliseconds since the Unix epoch – the same format generated by Time.now.to_i * 1000 in Ruby.

As of version 0.6.0, providing a SnowplowTracker::TrueTimestamp object as the timestamp argument will attach a true timestamp to the event, replacing the device timestamp. For example:

e = SnowplowTracker::Emitter.new('com.acme')
t = SnowplowTracker::Tracker.new(e)

t.track_page_view('http://example.com',
                  'Snowplow Ruby Tracker 0.6.0 released',
                  'http://www.referrer.com',
                   nil,
                   SnowplowTracker::TrueTimestamp.new(1471419787572))
Code language: PHP (php)

will send a page view event with a true timestamp to a collector at ‘com.acme’. An overridden device timestamp can be still be created in the following way:

e = SnowplowTracker::Emitter.new('com.acme')
t = SnowplowTracker::Tracker.new(e)

t.track_page_view('http://example.com',
                  'Snowplow Ruby Tracker 0.6.0 released',
                  'http://www.referrer.com',
                   nil,
                   1471419787572)
Code language: PHP (php)

Example

Here is an example of a page view event with custom context and timestamp arguments supplied:

tracker.track_page_view('http://www.film_company.com/movie_poster', nil, nil, [
  # First context
  SnowplowTracker::SelfDescribingJson.new(
    'iglu:com.my_company/movie_poster/jsonschema/1-0-0',
    {
      'movie_name' => 'Solaris',
      'poster_country' => 'JP',
      'poster_year$dt' => new Date(1978, 1, 1)
    }
  ),

  # Second context
  SnowplowTracker::SelfDescribingJson.new(
    'iglu:com.my_company/customer/jsonschema/1-0-0',
    {
      'p_buy' => 0.23,
      'segment' => 'young adult'
    }
  )
], 1368725287000)
Code language: PHP (php)

Track screen views with `track_screen_view`

Use track_screen_view() to track a user viewing a screen (or equivalent) within your app. Arguments are:

Argument	Description	Required?	Validation
`name`	Human-readable name for this screen	Yes	String
`id`	Unique identifier for this screen	No	String
`context`	Custom context	No	Array[SelfDescribingJson]
`tstamp`	When the screen was viewed	No	Positive integer

Example:

tracker.track_screen_view("HUD > Save Game", "screen23")
Code language: JavaScript (javascript)

Track page views with `track_page_view`

Use track_page_view() to track a user viewing a page within your app. Arguments are:

Argument	Description	Required?	Validation
`page_url`	The URL of the page	Yes	String
`page_title`	The title of the page	No	String
`referrer`	The address which linked to the page	No	String
`context`	Custom context	No	Array[SelfDescribingJson]
`tstamp`	When the pageview occurred	No	Positive integer

Example:

t.track_page_view("www.example.com", "example", "www.referrer.com")
Code language: CSS (css)

4.4 Track ecommerce transactions with `track-ecommerce-transaction()`

Use track_ecommerce_transaction() to track an ecommerce transaction. Arguments:

Argument	Description	Required?	Validation
`transaction`	Data for the whole transaction	Yes	Hash
`items`	Data for each item	Yes	Array of hashes
`context`	Custom context	No	Array[SelfDescribingJson]
`tstamp`	When the transaction event occurred	No	Positive integer

The transaction argument is a hash containing information about the transaction. Here are the fields supported in this hash:

Field	Description	Required?	Validation
`order_id`	ID of the eCommerce transaction	Yes	String
`total_value`	Total transaction value	Yes	Int or Float
`affiliation`	Transaction affiliation	No	String
`tax_value`	Transaction tax value	No	Int or Float
`shipping`	Delivery cost charged	No	Int or Float
`city`	Delivery address city	No	String
`state`	Delivery address state	No	String
`country`	Delivery address country	No	String
`currency`	Transaction currency	No	String

The transaction parameter might look like this:

{
  'order_id' => '12345'
  'total_value' => 35
  'city' => 'London'
  'country' => 'UK'
  'currency' => 'GBP'
}
Code language: PHP (php)

The items parameter is an array of hashes. Each hash represents one item in the transaction. Here are the fields supported for each item:

Argument	Description	Required?	Validation
`sku`	Item SKU	Yes	String
`price`	Item price	Yes	Int or Float
`quantity`	Item quantity	Yes	Int
`name`	Item name	No	String
`category`	Item category	No	String
`context`	Custom context	No	Array[SelfDescribingJson]

The items parameter might look like that:

[{
  'sku' => 'pbz0026',
  'price' => 20,
  'quantity' => 1,
  'category' => 'film'
},
{
  'sku' => 'pbz0038',
  'price' => 15,
  'quantity' => 1,
  'name' => 'red shoes'
}]
Code language: PHP (php)

The whole method call would look like this:

tracker.track_ecommerce_transaction({
  'order_id' => '12345'
  'total_value' => 35
  'city' => 'London'
  'country' => 'UK'
  'currency' => 'GBP'
},
[{
  'sku' => 'pbz0026',
  'price' => 20,
  'quantity' => 1,
  'category' => 'film'
},
{
  'sku' => 'pbz0038',
  'price' => 15,
  'quantity' => 1,
  'name' => 'red shoes'
}])
Code language: PHP (php)

This will fire three events: one for the transaction as a whole, which will include the fields in the transaction argument, and one for each item. The order_id and currency fields in the transaction argument will also be attached to each the items’ events.

All three events will have the same timestamp and same randomly generated Snowplow transaction ID.

Note that each item in the transaction can have its own custom context.

4.5 Track structured events with `track_struct_event`

Use track_struct_event() to track a custom event happening in your app which fits the Google Analytics-style structure of having up to five fields (with only the first two required):

Argument	Description	Required?	Validation
`category`	The grouping of structured events which this `action` belongs to	Yes	String
`action`	Defines the type of user interaction which this event involves	Yes	String
`label`	A string to provide additional dimensions to the event data	No	String
`property`	A string describing the object or the action performed on it	No	String
`value`	A value to provide numerical data about the event	No	Int or Float
`context`	Custom context	No	Array[SelfDescribingJson]
`tstamp`	When the structured event occurred	No	Positive integer

Example:

tracker.track_struct_event("shop", "add-to-basket", nil, "pcs", 2)
Code language: JavaScript (javascript)

4.7 Track self describing events with `track_self_describing_event`

This method was previously called track_unstruct_event.

Use track_self_describing_event() to track a custom event which consists of a name and a self-describing set of properties. This is useful when:

You want to track event types which are proprietary/specific to your business (i.e. not already part of Snowplow), or
You want to track events which have unpredictable or frequently changing properties

The arguments are as follows:

Argument	Description	Required?	Validation
`event_json`	The properties of the event	Yes	SelfDescribingJson
`context`	Custom context	No	Array[SelfDescribingJson]
`tstamp`	When the unstructured event occurred	No	Positive integer

Example:

tracker.track_self_describing_event(SnowplowTracker::SelfDescribingJson.new(
  "iglu:com.example_company/save_game/jsonschema/1-0-2",
  {
    "saveId" => "4321",
    "level" => 23,
    "difficultyLevel" => "HARD",
    "dlContent" => true
  }
))
Code language: PHP (php)

The event_json argument is SelfDescribingJson. It has two fields: “schema”, containing a pointer to the JSON schema for the event, and “data”, containing the event data itself. The data field must be flat: properties cannot be nested.

The keys of the event_json hash can be either strings or Ruby symbols.

Guest

Collecting data with Trackers and Webhooks

Common

Argument validation

Optional context argument

Optional timestamp argument

Example

Track screen views with `track_screen_view`

Track page views with `track_page_view`

4.4 Track ecommerce transactions with `track-ecommerce-transaction()`

4.5 Track structured events with `track_struct_event`

4.7 Track self describing events with `track_self_describing_event`

Guest

Collecting data with Trackers and Webhooks

Common

Argument validation

Optional context argument

Optional timestamp argument

Example

Track screen views with track_screen_view

Track page views with track_page_view

4.4 Track ecommerce transactions with track-ecommerce-transaction()

4.5 Track structured events with track_struct_event

4.7 Track self describing events with track_self_describing_event

Track screen views with `track_screen_view`

Track page views with `track_page_view`

4.4 Track ecommerce transactions with `track-ecommerce-transaction()`

4.5 Track structured events with `track_struct_event`

4.7 Track self describing events with `track_self_describing_event`