Skip to main content

Event parameters

This page lists 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.

To learn about self-describing events and how they are serialized in the tracker payload, visit this page.

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

Transaction 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. To learn about context entities and how they are serialized in the event payload, visit this page.

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_screenwidth and dvce_screenheighttextScreen / 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.

Was this page helpful?