Skip to main content

Snowplow atomic event properties

This page provides a reference for the standard fields that are found in all Snowplow events. These fields define the Snowplow tracker protocol, and are often called "atomic properties" or "atomic fields" in reference to the Snowplow atomic.events table. They're also sometimes called "canonical fields".

Fields that are populated during tracking have two names associated with them:

  • Payload property: a short payload name, to reduce the size of the HTTP request
  • Field name: a more descriptive column or field name

The field type refers to the data type in the enriched event data. For some fields, the type is different for the raw tracker payload and the enriched event. Again, this is to reduce the size of the HTTP request.

Different event fields are populated by different applications, such as tracker SDKs or enrichments. The source of data for each field is indicated in the tables below.

Values you provide in your tracking code have precedence over pipeline-derived values. For example, if you set useragent in your tracking code, the YAUAA enrichment will use that value, rather than overriding it with the value from the User-Agent HTTP header.

Validation​

During enrichment, atomic property values are validated against the atomic schema. If a required field is missing or invalid, for example the wrong type or length, Enrich will process the event as a failed event. The reqd? values in these tables specify whether a field is required for a Snowplow event.

The tables show the default maximum lengths for string fields. You can configure different maximum lengths for specific fields by setting atomicFieldsLimits in the Enrich configuration. These can be more permissive than the limits in the atomic schema. In fact, the page_url, page_referrer, and mkt_clickid fields already have larger maximum lengths in the default Enrich configuration than in the atomic schema.

Some identifiers require UUID strings. Snowplow components use UUIDv4, but the pipeline will accept any valid UUID, regardless of version.

Any payload that conforms to this protocol is a valid Snowplow event payload, whether it's sent by a Snowplow tracker SDK, a webhook, or a custom application. If you want to get into the details, check out these example HTTP requests. In total, the tracker protocol defines 131 fields, of which 89 are in use by Snowplow applications.

Common fields​

These fields are common to all Snowplow events, regardless of platform or event type.

Event fields​

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

Payload propertyField nameTypeDescriptionReqd?ExampleSourceWebMobile
eeventstring, max length 128The type of event recordedYespage_viewTracking✅✅
eidevent_idUUID stringA UUID for each eventYesc6ef3124-b53a-4b13-a233-0088f79dcbcbTracking (or enrichment if empty)✅✅
event_fingerprintstring, max length 128Hash client-set event fields, used to de-dupe recordsNoAADCE520E20C2899F4CED228A79A3083Event fingerprint enrichment✅✅

This table shows the possible values for the event field:

Event typePayload e valueField event value
Self-describing eventueunstruct
Page viewpvpage_view
Page pingpppage_ping
Structured eventsestruct
Legacy ecommerce eventstr and titransaction and transaction_item

User fields​

Read more about tracking and using these fields in the OOTB user and session data and identifiers pages.

The domain_userid is regarded as the most reliable session based identifier for most use cases. It's treated as the primary user_identifier field in our data models that rely on sessionization, including the Unified Digital data model.

The domain_sessionidx is the number or index of the current user session. For example, an event occurring during a user's first session would have domain_sessionidx set to 1. The JavaScript tracker calculates this field by storing a visit count in a first-party cookie.

The equivalent values on mobile are tracked in a session entity.

The network_userid is set by a Collector cookie by default. You can override it by setting a network_userid with your tracker.

The IP address is also added to the event by the Collector, if you didn't provide one in your tracking code. Snowplow supports both IPv4 and IPv6 addresses, as long as a domain is compatible with the IPv6 network.

Payload propertyField nameTypeDescriptionReqd?ExampleSourceWebMobile
uiduser_idstring, max length 255Unique identifier for user, set by the business using setUserIdNoc94f860b-1266-4dad-ae57-3a36a414a521Tracking✅✅
duiddomain_useridstring, max length 128Unique identifier for a user, based on a first party cookieNo4b0dfa75-9a8c-46a1-9691-01add9db4200Tracking✅❌
tnuidnetwork_useridstring, max length 128User ID set by Snowplow using server-set cookieNoecdff4d0-9175-40ac-a8bb-325c49733607Tracking or pipeline✅✅
siddomain_sessionidUUID stringUnique identifier (UUID) for this visit of this domain_userid to this domainNoc6ef3124-b53a-4b13-a233-0088f79dcbcbTracking✅❌
viddomain_sessionidxintegerIndex of number of visits that this domain_userid has made to this domainNo3Tracking✅❌
ipuser_ipaddressstring, max length 128User IP address, can be overwritten with the IP anonymization enrichmentNo92.231.54.234Tracking or IP anonymization enrichment✅✅

Application fields​

Use the application ID to distinguish events tracked from different applications or websites by the same Snowplow stack.

The platform ID is used to distinguish the same app running on different platforms, e.g. iOS vs web.

Payload propertyField nameTypeDescriptionReqd?ExampleSourceWebMobile
aidapp_idstring, max length 255Application IDYessnow-game-androidTracking✅✅
pplatformstring, max length 255Platform the app runs onYeswebTracking✅✅
tnaname_trackerstring, max length 128Tracker namespaceNotracker_1Tracking✅✅

This table shows the possible values for the platform field:

Platformplatform value
Web, including mobile webweb
Mobile, tabletmob
Desktop, laptoppc
Server-side applicationsrv
General applicationapp
Connected TVtv
Games consolecnsl
Internet of Thingsiot
Headset (e.g., AR, VR)headset
Tracker namespacing

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

Time and date fields​

The etl_tstamp field records when the event was validated and enriched, not when it was loaded into the warehouse. The name is historical.

Most Snowplow trackers have built-in capability for tracking os_timezone. See the geolocation and timezone tracking page for tracker-specific configuration details.

Payload propertyField nameTypeDescriptionReqd?ExampleSourceWebMobile
collector_tstamptimestampTimestamp for the event recorded by the CollectorYes2013-11-26 00:02:05.123Pipeline✅✅
dtmdvce_created_tstamptimestampTimestamp for the event recorded on the client deviceNo2013-11-26 00:03:57.885Tracking✅✅
stmdvce_sent_tstamptimestampTimestamp when event occurred, as recorded by client deviceNo2013-11-26 00:03:58.032Tracking✅✅
etl_tstamptimestampTimestamp for when the event was validated and enrichedNo2017-01-26 00:01:25.292Pipeline✅✅
derived_tstamptimestampTimestamp making allowance for inaccurate device clockNo2013-11-26 00:02:04.123Default enrichment✅✅
ttmtrue_tstamptimestampUser-set "true timestamp" for the eventNo2013-11-26 00:02:04.123Tracking✅✅
load_tstamp timestampTimestamp for when the data was loaded into the warehouseNo2013-11-26 00:02:04.123Pipeline✅✅
tzos_timezonestring, max length 255Client operating system timezoneNoEurope/LondonTracking✅✅

The trackers send timestamp properties as int in the payload, representing milliseconds since the Unix epoch, e.g. 1361553733313. They're converted to timestamp type during enrichment. Similarly, the tz property is URL-encoded in the payload, e.g. Europe%2FLondon, and decoded during enrichment.

Read more about Snowplow timestamps here.

Device fields​

The dvce_screenheight and dvce_screenwidth screen resolution fields originate from a single res payload property. It's a string with the format "<width>x<height>", e.g. 1900x1024. During enrichment, this string is split into the two separate integer fields.

Payload propertyField nameTypeDescriptionReqd?ExampleSourceWebMobile
resdvce_screenheightintegerScreen height in pixelsNo1024Tracking✅✅
resdvce_screenwidthintegerScreen width in pixelsNo1900Tracking✅✅

For more information on this topic check out the device data page.

IP address fields​

These fields are populated by the IP enrichment, based on the user_ipaddress field.

Field nameTypeDescriptionReqd?ExampleSourceWebMobile
ip_ispstring, max length 100User's ISPNoFDN CommunicationsIP enrichment✅✅
ip_organizationstring, max length 128Organization associated with the user's IP address - defaults to ISP name if none is foundNoBouygues TelecomIP enrichment✅✅
ip_domainstring, max length 128Second level domain name associated with the user's IP addressNonuvox.netIP enrichment✅✅
ip_netspeedstring, max length 100User's connection typeNoCable/DSLIP enrichment✅✅

Location fields​

These fields are populated by the IP enrichment, based on the IP address.

Field nameTypeDescriptionReqd?ExampleSourceWebMobile
geo_countrystring, max length 2ISO 3166-1 code for the country the user is located inNoGB, USIP enrichment✅✅
geo_regionstring, max length 3ISO-3166-2 code for country region the user is inNoI9, TXIP enrichment✅✅
geo_citystring, max length 75City the user is inNoNew York, LondonIP enrichment✅✅
geo_zipcodestring, max length 15Postcode the user is inNo94109IP enrichment✅✅
geo_latitudefloatUser location latitudeNo37.443604IP enrichment✅✅
geo_longitudefloatUser location longitudeNo-122.4124IP enrichment✅✅
geo_region_namestring, max length 100User region nameNoFloridaIP enrichment✅✅
geo_timezonestring, max length 64User timezone nameNoEurope/LondonIP enrichment✅✅

For more information on this topic check out the geolocation data page.

Marketing fields​

These fields are populated by the campaign attribution enrichment.

Field nameTypeDescriptionReqd?ExampleSourceWebMobile
mkt_mediumstring, max length 255Type of traffic sourceNo'cpc', 'affiliate', 'organic', 'social'Campaign attribution enrichment✅✅
mkt_sourcestring, max length 255The company or website where the traffic came fromNo'Google', 'Facebook'Campaign attribution enrichment✅✅
mkt_termstring, max length 255Any keywords associated with the referrerNo'new age tarot decks'Campaign attribution enrichment✅✅
mkt_contentstring, max length 500The content of the ad, or an ID so that it can be looked upNo13894723Campaign attribution enrichment✅✅
mkt_campaignstring, max length 255The campaign IDNo'diageo-123'Campaign attribution enrichment✅✅
mkt_clickidstring, max length 1000The click IDNo'ac3d8e459'Campaign attribution enrichment✅✅
mkt_networkstring, max length 64The ad network to which the click ID belongsNo'DoubleClick'Campaign attribution enrichment✅✅

Cross-domain tracking fields​

The pipeline populates these fields by default if the event's url has a cross-navigation querystring.

Payload propertyField nameTypeDescriptionReqd?ExampleSourceWebMobile
refr_domain_useridstring, max length 128The Snowplow domain_userid of the referring websiteNobc2e92ec6c204a14Default enrichment✅✅
refr_dvce_tstamptimestampThe time of attaching the domain_userid to the inbound linkNo2013-11-26 00:02:05Default enrichment✅✅

Snowplow versions fields​

These fields record the versions of the various Snowplow components involved in processing the event.

Payload propertyField nameTypeDescriptionReqd?ExampleSourceWebMobile
tvv_trackerstring, max length 100Tracker versionYesjs-3.0.0Tracking✅✅
v_collectorstring, max length 100Collector versionYesssc-2.1.0-kinesisPipeline✅✅
v_etlstring, max length 100ETL application versionsYessnowplow-micro-1.1.0-common-1.4.2Default enrichment✅✅

Web-specific fields​

These fields apply mainly to events from web.

For more information about these fields check out the device and browser, page and screen view, and links and referrers overview pages.

Page fields​

The url, refr and page payload properties are URL-encoded in the payload, e.g. https%3A%2F%2Fwww.snowplow.io%2F or Snowplow%20Behavoral%20Data, and decoded during enrichment.

The url property is further parsed during enrichment to populate the various page_url* fields. Similarly, the refr property is parsed to populate the various refr_* fields.

Payload propertyField nameTypeDescriptionReqd?ExampleSourceWebMobile
urlpage_urlstring, max length 10000The page URLNohttps://www.snowplow.io/product/index.html?id=GTM-DLRG#conclusionTracking✅❌
page_urlschemestring, max length 16Scheme, also known as protocolNohttpsDefault enrichment✅❌
page_urlhoststring, max length 255Host, also known as domainNowww.snowplow.ioDefault enrichment✅❌
page_urlportintegerPort if specified, scheme dependent if not; 443 for HTTPS, 80 for HTTPNo443Default enrichment✅❌
page_urlpathstring, max length 3000Path to pageNo/product/index.htmlDefault enrichment✅❌
page_urlquerystring, max length 6000QuerystringNoid=GTM-DLRGDefault enrichment✅❌
page_urlfragmentstring, max length 3000Fragment, also known as anchorNoconclusionDefault enrichment✅❌
pagepage_titlestring, max length 2000Web page titleNoSnowplow Behavioral DataTracking✅❌
refrpage_referrerstring, max length 10000URL of the referrerNohttps://www.google.com/search?q=psychic+oracle+cardsTracking✅❌
refr_urlschemestring, max length 16Referrer schemeNohttpsDefault enrichment✅❌
refr_urlhoststring, max length 255Referrer hostNowww.google.comDefault enrichment✅❌
refr_urlportintegerReferrer portNo443Default enrichment✅❌
refr_urlpathstring, max length 6000Referrer page pathNo/searchDefault enrichment✅❌
refr_urlquerystring, max length 6000Referrer URL querystringNoq=psychic+oracle+cardsDefault enrichment✅❌
refr_urlfragmentstring, max length 3000Referrer URL fragmentNoDefault enrichment✅❌
refr_mediumstring, max length 25Type of referrerNosearchReferrer parser enrichment✅❌
refr_sourcestring, max length 50Name of referrer if recognizedNoGoogleReferrer parser enrichment✅❌
refr_termstring, max length 255Keywords if source is a search engineNopsychic oracle cardsReferrer parser enrichment✅❌

Document fields​

The doc_width and doc_height page size fields originate from a single ds payload property. It's a string with the format "<width>x<height>", e.g. 3000x1024. During enrichment, this string is split into the two separate integer fields.

Payload propertyField nameTypeDescriptionReqd?ExampleSourceWebMobile
csdoc_charsetstring, max length 128The page's character encodingNoUTF-8Tracking✅❌
dsdoc_widthintegerThe page's width in pixelsNo1024Tracking✅❌
dsdoc_heightintegerThe page's height in pixelsNo3000Tracking✅❌

Browser fields​

The br_viewwidth and br_viewheight page size fields originate from a single vp payload property. It's a string with the format "<width>x<height>", e.g. 1000x1000. During enrichment, this string is split into the two separate integer fields.

Payload propertyField nameTypeDescriptionReqd?ExampleSourceWebMobile
langbr_langstring, max length 255Language the browser is set toNoen-GBTracking✅❌
cookiebr_cookiesinteger booleanWhether the browser is accepting cookiesNo1Tracking✅❌
cdbr_colordepthstring, max length 12Bit depth of the browser color paletteNo24Tracking✅❌
vpbr_viewwidthintegerViewport widthNo1000Tracking✅❌
vpbr_viewheightintegerViewport heightNo1000Tracking✅❌
uauseragentstring, max length 1000Raw useragentNoMozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:105.0) Gecko/20100101 Firefox/105.0Tracking or pipeline✅✅

Baked-in event fields​

Baked-in event data is stored in specific default fields, rather than in self-describing event or entity columns.

Page views​

There are no fields that are specific to page view events. All the relevant fields are included in the standard fields available for any web-based event e.g. page_url, or page_title.

Page pings​

Page ping events include four additional fields. They indicate how a user has scrolled over a web page since the last page ping:

Payload propertyField nameTypeDescriptionReqd?Example
pp_mixpp_xoffset_minintegerMinimum page x offset seen in the last ping periodNo10
pp_maxpp_xoffset_maxintegerMaximum page x offset seen in the last ping periodNo100
pp_miypp_yoffset_minintegerMinimum page y offset seen in the last ping periodNo5
pp_maypp_yoffset_maxintegerMaximum page y offset seen in the last ping periodNo200

Structured events​

Structured events use these fields to capture event data:

Payload propertyField nameTypeDescriptionReqd?Example
se_case_categorystring, max length 1000Category of eventYes *ecomm, video
se_acse_actionstring, max length 1000Action performed, or event nameYes *add-to-basket, play-video
se_lase_labelstring, max length 4096The object of the action e.g. the ID of the video played. or SKU of the product added to basketNopbz00123
se_prse_propertystring, max length 1000A property associated with the object of the actionNoHD, large
se_vase_valuedecimalA value associated with the event or action e.g. the value of goods added-to-basketNo9.99

* These fields are only required for structured events.

Self-describing event fields​

For self-describing events, the pipeline extracts data from the event schema and populates the following fields:

Field nameTypeDescriptionReqd?ExampleSourceWebMobile
event_vendorstring, max length 1000Business that defined the eventYescom.acmeDefault enrichment✅✅
event_namestring, max length 1000Event nameYeslink_clickDefault enrichment✅✅
event_formatstring, max length 128Format for event; always jsonschemaYesjsonschemaDefault enrichment✅✅
event_versionstring, max length 128Version of event schemaYes1-0-2Default enrichment✅✅
Extra columns for self-describing event data

Data in self-describing events or entities is added as additional columns, rather than in these standard atomic fields.

Check out the warehouse table structure page to learn more.

Deprecated fields​

We have deprecated the following fields. They're no longer populated by Snowplow trackers or enrichments, but they're still part of the Snowplow tracker protocol:

Field nameTypeDescriptionReqd?ExampleSourceWebMobile
txn_idintegerTransaction ID set client-side, used to de-dupe recordsNo421828Deprecated✅✅
dvce_typestring, max length 50Type of deviceNoComputerDeprecated✅✅
dvce_ismobileinteger booleanIs the device mobile?No1Deprecated✅✅
os_namestring, max length 50Name of operating systemNoAndroidDeprecated✅✅
os_familystring, max length 50Operating system familyNoLinuxDeprecated✅✅
os_manufacturerstring, max length 50Company responsible for OSNoAppleDeprecated✅✅
user_fingerprintstring, max length 128A user fingerprint generated by looking at the individual browser featuresNo2161814971Deprecated❌❌
br_namestring, max length 50Browser nameNoFirefox 12Deprecated❌❌
br_versionstring, max length 50Browser versionNo12.0Deprecated❌❌
br_familystring, max length 50Browser familyNoFirefoxDeprecated❌❌
br_typestring, max length 50Browser typeNoBrowserDeprecated❌❌
br_renderenginestring, max length 50Browser rendering engineNoGECKODeprecated❌❌
br_features_pdfinteger booleanWhether the browser recognizes PDFsNo1Deprecated✅❌
br_features_flashinteger booleanWhether Flash is installedNo1Deprecated✅❌
br_features_javainteger booleanWhether Java is installedNo1Deprecated✅❌
br_features_directorinteger booleanWhether Adobe Shockwave is installedNo1Deprecated✅❌
br_features_quicktimeinteger booleanWhether QuickTime is installedNo1Deprecated✅❌
br_features_realplayerinteger booleanWhether RealPlayer is installedNo1Deprecated✅❌
br_features_windowsmediainteger booleanWhether mplayer2 is installedNo1Deprecated✅❌
br_features_gearsinteger booleanWhether Google Gears is installedNo1Deprecated✅❌
br_features_silverlightinteger booleanWhether Microsoft Silverlight is installedNo1Deprecated✅❌

Legacy ecommerce fields​

There are a large number of fields in the tracker protocol specifically for legacy ecommerce transaction and transaction_item events.

Fields that start tr_ relate to the transaction as a whole. Fields that start ti_ refer to the specific item included in the transaction, e.g. a product in the basket.

Single transactions typically span multiple lines of data: there will be a single line where event = transaction, where the tr_ fields are set, and multiple lines (one for each product included) where event = transaction_item and the ti_ fields are set.

Field nameTypeDescriptionReqd?Example
tr_orderidstring, max length 255Order IDYes#134
tr_affiliationstring, max length 255Transaction affiliation (e.g. store where sale took place)Noweb
tr_totaldecimalTotal transaction valueYes12.99
tr_taxdecimalTotal tax included in transaction valueNo3.00
tr_shippingdecimalDelivery cost chargedNo0.00
tr_total_base *decimalTotal in base currencyNo12.99
tr_tax_base *decimalTotal tax in base currencyNo3.00
tr_shipping_base *decimalDelivery cost in base currencyNo0.00
tr_citystring, max length 255Delivery address, cityNoLondon
tr_statestring, max length 255Delivery address, stateNoWashington
tr_countrystring, max length 255Delivery address, countryNoFrance
tr_currencystring, max length 3CurrencyNoUSD
ti_orderidstring, max length 255Order IDYes#134
ti_skustring, max length 255Product SKUYespbz00123
ti_namestring, max length 255Product nameNoCone pendulum
ti_categorystring, max length 255Product categoryNoNew Age
ti_pricedecimalProduct unit priceYes9.99
ti_price_base *decimalPrice in base currencyNo9.99
ti_quantityintegerNumber of product in transactionYes2
ti_currencystring, max length 3CurrencyNoEUR
base_currency *string, max length 3Reporting currencyNoGBP

* Set exclusively by the Currency conversion enrichment.

On this page

Want to see a custom demo?

Our technical experts are here to help.

Book a demo