Tracker Specification - OXYGEN-MARKET/oxygen-market.github.io GitHub Wiki

HOME > SNOWPLOW TECHNICAL DOCUMENTATION > Trackers > Tracker Specification

• 1. Overview
• 2. Essential features
• 3. Power features
• 4. Advanced features

This page describes the feature list for Snowplow Trackers. The Snowplow Tracker Protocol may also be helpful as it contains information about specific event fields.

These are the features which all Snowplow Trackers should support from the first version.

• Name-value pairs which should automatically be added to the payload of every event:

  • tv: tracker version, of the form "py-0.5.0"
  • tna: user-defined name for the Tracker instance which can be used to determine which tracker sent which events
  • aid: optional application ID, set by the user when initializing the tracker
  • eid: version 4 randomly generated UUID used to distinguish between events

• Setter methods to set persistent data which gets sent with every event:

  • SetUserId
  • SetPlatform (should only allow the platforms specified in the Tracker Protocol)
  • SetScreenResolution
  • SetViewport
  • SetColorDepth
  • SetTimezone
  • SetLang

• Methods with the following signatures (question marks fields which may be null):

  • TrackPageView(string pageUri, string? pageTitle, string? referrer)
  • TrackStructEvent(string category, string action, string? label, string? property, num? value)
  • TrackUnstructEvent(selfDescribingJson eventJson)
  • TrackEcommerceTransaction(string orderId, num totalValue, string? affiliation, num? taxValue, num? shipping, string? city, string? state, string? country, string? currency, list<TransactionItem>? items)

• The elements of the TransactionItem list should have the following fields: `TransactionItem(string sku, num price, num quantity, string? name, string? category)

• Each of the above methods should also accept two additional optional arguments: a list of custom context self-describing JSONs, and a timestamp in milliseconds since the Unix epoch. If the timestamp is not provided by the user it should be added by the tracker.

• Custom context JSONs and unstructured event JSONs should by default be base 64 encoded before being added to the payload, but there should be an option to leave them unencoded to make debugging easier

• Empty strings and null values should never be added to the payload for an event.

These are features which all server-side trackers should aim to support.

• A Subject class representing a single user being tracked. At any one time, the Tracker instance will have one active Subject associated with it, and all that Subject's data (user ID, timezone, and so on) will be sent with every event.
• The ability to call all of the Subject's setter methods from the Tracker instance. In some languages this can be done by metaprogramming rather than copying out all the Subject methods into the Tracker class.
• An Emitter class which governs sending events generated by the Tracker class
• The ability to specify the port to connect to
• The ability to send requests over both HTTP and HTTPS
• The ability to send both GET and POST requests
• An in-memory buffer which is filled with events until a threshold is reached, at which point it is "flushed" and all the events are sent simultaneously in a single POST request
• The ability for users to manually flush the buffer
• The ability to send events asynchronously, usually using an AsyncEmitter class which inherits from Emitter
• The ability for users to manually and synchronously flush the buffer, for instance to send stored events before closing the application
• The ability for a Tracker to send events to more than one Emitter
• A Tracker method which flushes all emitters to which that Tracker sends events
• The ability to specify an "on success" callback which executes when all events in a flush are sent successfully (that is, with status code 200). The callback should take one argument: the number of events sent.
• The ability to specify an "on failure" callback which executes when not all events in a flush are sent successfully. The callback should take two arguments: the number of events sent successfully, and a list of the events which were not sent successfully.
• For dynamic languages, some sort of type checking. This is especially useful for ensuring that self-describing JSON arguments are constructed correctly.
• Logging messages to the console
• The ability for users to set the level of messages to log. The choices are:
  • Off: Nothing logged
  • Warn: Notifications for events fired which didn't return with status code 200
  • Info: Notifications for all events fired
  • Debug: Contents of all events fired in JSON form

These are advanced features which most trackers do not support.

• The ability to set a timer which periodically flushes the buffer
• The ability to store events when offline and attempt to resend them when online
• A RedisEmitter which sends events to a Redis database
• An emitter which sends events to a task queue (such as Celery)