Skip to main content

Tracker Protocol Overview

Snowplow trackers fire events, which are either GET or POST requests to a Snowplow collector. By adding parameters to these requests, trackers can pass data into the collector for processing by Snowplow.

The Snowplow Tracker Protocol is the list of all the parameters that Snowplow trackers use when firing events to push data into the Snowplow collectors. Each parameter maps onto one or more fields in the Snowplow events table employed in storage.

This page is for you if you want to understand the tracker payload in more detail, and especially if you are building your own tracker. In the latter case, utilizing the parameters documented here will ensure that your tracker works with the rest of the Snowplow stack.

caution

When the event is sent from a Snowplow tracker, all parameters should be stringified. Those strings are parsed back to their actual type during Enrichment.

Snowplow events​

At its heart, Snowplow is a platform for granular tracking of events. In the tracker protocol, each event is denoted by an e=... parameter.

There are 3 categories of events:

  • Standard events, such as page views, page pings and transactions
  • Custom self-describing events based on a schema
  • Legacy custom structured events, which we don’t recommend using
info

Historically, custom self-describing events were called “unstructured” and the legacy custom events were called “structured”. This terminology can be confusing, so we don’t use it anymore. However, you might find its remnants in some of the APIs.

Type of trackingEvent type (value of e)
Self-describing eventue
Pageview trackingpv
Page pingspp
Ecommerce transaction trackingtr and ti
Custom structured eventse

Additionally, entities can be attached to events which gives additional context to the event.

Self-describing events​

Structuring your data with schemas to perform self-describing event tracking is the defacto way to track events with Snowplow and allows any arbitrary name: value pairs to be captured with the event.

An example of a self-describing event for a product view event:

{
"schema": "iglu:com.my_company/viewed_product/jsonschema/1-0-0",
"data": {
"product_id": "ASO01043",
"price": 49.95
}
}
info

"iglu:com.my_company/viewed_product/jsonschema/1-0-0" respresents a self-describing JSON. It is used to validate the event data against a predefined JSON Schema as part of a Snowplow pipeline.

The tracker will wrap this self-describing JSON in an outer self-describing JSON, which is what gets sent in the payload:

{

// Tells Snowplow this is an self-describing event
"schema": "iglu:com.snowplowanalytics.snowplow/unstruct_event/jsonschema/1-0-0",
"data": {

// Tells Snowplow this is a viewed_product event
"schema": "iglu:com.my_company/viewed_product/jsonschema/1-0-0",
"data": {

// The event data itself
"product_id": "ASO01043",
"price": 49.95
}
}
}

As well as setting e=ue, there are two custom event specific parameters that can be populated with the outer self-describing JSON:

ParameterTable ColumnTypeDescription
ue_pxunstruct_eventJSON (URL-safe Base64 encoded)The properties of the event
ue_prunstruct_eventJSONThe properties of the event

The tracker can decide to pass the ue_px or the ue_pr parameter. Encoding properties into URL-safe Base64 allows is the recommended approach although does sacrifice readability.

Other Events​

There are a number of core Snowplow events which do not follow the self-describing event format.

Page Views​

Pageview tracking is used to record views of web pages.

Currently, recording a pageview involves recording an event where e=pv. All the fields associated with web events can be tracked. There are no other pageview specific fields.

Page Pings​

Page pings are used to record users engaging with content on a web page after it has originally loaded. For example, it can be used to track how far down an article a user scrolls.

If enabled, the activity tracking function checks for engagement with a page after load. (E.g. mousemovement, scrolling etc...).

Page pings are identified by e=pp. As well as all the standard web fields, there are four additional fields that pp includes, which are used to identify how users are scrolling over web pages:

ParameterTable ColumnTypeDescription
pp_mixpp_xoffset_minintegerMinimum page x offset seen in the last ping period
pp_maxpp_xoffset_maxintegerMaximum page x offset seen in the last ping period
pp_miypp_yoffset_minintegerMinimum page y offset seen in the last ping period
pp_maypp_yoffset_maxintegerMaximum page y offset seen in the last ping period

Transaction tracking​

Trnasaction events allow you to track a transaction. The items of the transaction can be tracked using Transaction Item events.

ParameterTable ColumnTypeDescription
tr_idtr_orderidtextOrder ID
tr_aftr_affiliationtextTransaction affiliation (e.g. channel)
tr_tttr_totaldecimalTransaction total value
tr_txtr_taxdecimalTransaction tax value (i.e. amount of VAT included)
tr_shtr_shippingdecimalDelivery cost charged
tr_citr_citytextDelivery address: city
tr_sttr_statetextDelivery address: state
tr_cotr_countrytextDelivery address: country
tr_cutr_currencytextTransaction Currency

Transaction item events​

Transaction item events are separate events, representing the items of a transaction, which are linked to a Transaction event via ti_id which should map to tr_id of a transaction event.

ParameterTable ColumnTypeDescriptionExample values
ti_idti_orderidtextOrder ID12345
ti_skti_skutextItem SKUYes
ti_nmti_nametextItem nameYes
ti_cati_categorytextItem categoryYes
ti_prti_pricedecimalItem priceYes
ti_quti_quantityintegerItem quantityYes
ti_cuti_currencytextCurrencyYes

Structured event tracking​

info

Structured event tracking is a legacy format used to track events that were not natively supported by Snowplow.

We recommend using self-describing events for custom event tracking.

As well as setting e=se, there are five custom event specific parameters that can be set:

ParameterTable ColumnTypeDescriptionExample values
se_case_categorytextThe category of eventEcomm, Media
se_acse_actiontextThe action / event itselfadd-to-basket, play-video
se_lase_labeltextA label often used to refer to the 'object' the action is performed ondog-skateboarding-video
se_prse_propertytextA property associated with either the action or the objecthd
se_vase_valuedecimalA value associated with the user action13.99

Event Entity Tracking​

Custom entities can be used to add additional context to an event.

Each individual entity is a self-describing JSON such as:

{
"schema": "iglu:com.my_company/user/jsonschema/1-0-0",
"data": {
"fb_uid": "9999xyz"
}
}
info

"iglu:com.my_company/user/jsonschema/1-0-0" respresents a self-describing JSON. It is used to validate the event data against a predefined JSON Schema as part of a Snowplow pipeline.

All entities attached to an event will be wrapped in an array by the user and passed to the tracker, which will wrap them in a self-describing JSON:

{

// Tells Snowplow this is an array of custom contexts
"schema": "iglu:com.snowplowanalytics.snowplow/contexts/jsonschema/1-0-0",
"data": [
{

// Tells Snowplow that this is a "user" context
"schema": "iglu:com.my_company/user/jsonschema/1-0-0",
"data": {

// The context data itself
"fb_uid": "9999xyz"
}
}
]
}

Trackers can be configured to encode the context into URL-safe Base64 to ensure that no data is lost or corrupted. The downside is that the data will be bigger and less readable.

ParameterTable ColumnTypeDescriptionExample values
cocontextJSONAn array of custom contexts%7B%22schema%22:%22iglu:com.snowplowanalytics.snowplow/contexts/jsonschema/1-0-0%22,%22data%22:%5B%7B%22schema%22:%22iglu:com.my_company/user/jsonschema/1-0-0%22,%22data%22:%7B%22fb_uid%22:%229999xyz%22%7D%7D%5D%7D
cxcontextJSON (URL-safe Base64 encoded)An array of custom contextsew0KICBzY2hlbWE6ICdpZ2x1OmNvbS5zbm93cGxvd2FuYWx5dGljcy5zbm93cGxvdy9jb250ZXh0cy9qc29uc2NoZW1hLzEtMC0wJyANCiAgZGF0YToge1sNCiAgICB7DQogICAgICBzY2hlbWE6ICdpZ2x1OmNvbS5teV9jb21wYW55L3VzZXIvanNvbnNjaGVtYS8xLTAtMCcgDQogICAgICBkYXRhOiB7DQogICAgICAgIGZiX3VpZDogJzk5OTl4eXonDQogICAgICB9DQogICAgfQ0KICBdfQ0KfQ==

Common Parameters​

Event parameters​

ParameterTable ColumnTypeDescriptionExample values
eeventtextEvent type(See table above)
eidevent_idtextEvent UUID606adff6-9ccc-41f4-8807-db8fdb600df8
caution

Every line of data passed from the tracker should contain an event field (e) to denote the type of event being tracked (See the events section for possible values).

info

The event ID (eid) is the unique identifier (UUID) for this row. This should be generated by trackers, but if missing will be generated by the enrichment process.

Application parameters​

ParameterTable ColumnTypeDescriptionExample values
tnaname_trackertextThe tracker namespacetracker_1
aidapp_idtextUnique identifier for website / applicationsnow-game-android
pplatformtextThe platform the app runs onweb, mob, app
tvv_trackertextIdentifier for Snowplow trackerjs-2.16.2
info

The tracker namespace parameter is used to distinguish between different trackers. The name can be any string that does not contain a colon or semi-colon character. Tracker namespacing allows you to run multiple trackers, pinging to different collectors.

Allowed platform values:

Platformp value
Web (including Mobile Web)web
Mobile/Tabletmob
Desktop/Laptop/Netbookpc
Server-Side Appsrv
General Appapp
Connected TVtv
Games Consolecnsl
Internet of Thingsiot

Timestamp parameters​

ParameterTable ColumnTypeDescriptionExample values
dtmdvce_created_tstampintTimestamp when event occurred, as recorded by client device1361553733313
stmdvce_sent_tstampintTimestamp when event was sent by client device to collector1361553733371
ttmtrue_tstampintUser-set exact timestamp1361553733371
tzos_timezonetextTime zone of client devices OSEurope%2FLondon
info

The Snowplow Collector will also capture collector_tstamp which the time the event arrived at the collector.

Snowplow will also calculate a derived_tstamp which attempts to make allowances for innaccurate device clocks. The ttm field is used for a timestamp set on the client which should be taken as accurate. This will overwrite the derived_tstamp if set.

ParameterTable ColumnTypeDescriptionExample values
duiddomain_useridtextUnique identifier for a user, based on a first party cookie (so domain specific)aeb1691c5a0ee5a6
tnuidnetwork_useridtextCan be used be a tracker to overwrite the nuidecdff4d0-9175-40ac-a8bb-325c49733607
uiduser_idtextUnique identifier for user, set by the business using setUserIdjon.doe@email.com
viddomain_sessionidxintIndex of number of visits that this user_id has made to this domain. 1 is first visit.1
siddomain_sessionidtextUnique identifier (UUID) for this visit of this user_id to this domain9c65e7f3-8e8e-470d-b243-910b5b300da0
ipuser_ipaddresstextIP address override. This is useful, if traffic is being proxied to a Snowplow collector (optional, as IP Address will be automatically captured by collector)37.157.33.178
info

network_userid is captured via a cookie set by the Snowplow Collector. It can be overriden by setting tnuid on a Tracker request payload but is typically expected to be populated by the collector cookies.

Platform parameters​

ParameterTable ColumnTypeDescriptionExample values
urlpage_urltextPage URLhttp%3A%2F%2Ftest.psybazaar.com%2F2-tarot-cards
uauseragenttextUseragentMozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:105.0) Gecko/20100101 Firefox/105.0
pagepage_titletextPage titleSnowplow%20Behavoral%20Data
refrpage_referrertextReferrer URLhttp%3A%2F%2Fwww.snowplow.io%2F
cookiebr_cookiesbooleanDoes the browser permit cookies?1
langbr_langtextLanguage the browser is set toen-US
f_pdfbr_features or br_features_pdfbooleanAdobe PDF plugin installed?1
cdbr_colordepthintegerBrowser color depth24
csdoc_charsettextWeb page's character encodingUTF-8
dsdoc_width and doc_heighttextWeb page width and height1090x1152
vpbr_viewwidth and br_viewheighttextBrowser viewport width and height1105x390
resdvce_screenheight and dvce_screenwidthtextScreen / monitor resolution1280x1024
macmac_addresstextMAC address for the device running the tracker12:34:56:78:9A:BC

Reserved parameters​

u is a reserved parameter because it is used for click tracking in the Pixel Tracker.

Other event properties​

Alongside the Tracker Protocol JSON Payload, it's possible to capture additional information on HTTP Requests.

HTTP Headers​

Snowplow Collectors will collect any standard HTTP headers and the values of these headers can be extracted during Enrichment. The HTTP header extractor enrichment can be configured for the headers you wish to extract.

Additionally, the following two headers can be sent on requests:

HeaderAllowed ValuesDescription
Content-Typeapplication/jsonSee MDN Content-Type
SP-Anonymous*Enables Server Side Anonymization, preventing the User IP Address and Network User ID from being collectoed

Snowplow Collectors will collect any cookie information sent in the Cookie HTTP header. Cookies can be attached to events using the Cookie extractor enrichment