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.

The reqd? values in these tables specify whether a field is required for a Snowplow event. Required fields will always have values.

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 property	Field name	Type	Description	Reqd?	Example	Source	Web	Mobile
e	event	text	The type of event recorded	Yes	page_view	Tracking	✅	✅
eid	event_id	text	A UUID for each event	Yes	c6ef3124-b53a-4b13-a233-0088f79dcbcb	Tracking (or enrichment if empty)	✅	✅
	event_fingerprint	text	Hash client-set event fields, used to de-dupe records	No	AADCE520E20C2899F4CED228A79A3083	Event fingerprint enrichment	✅	✅

This table shows the possible values for the event field:

Event type	Payload e value	Field event value
Self-describing event	ue	unstruct
Page view	pv	page_view
Page ping	pp	page_ping
Structured event	se	struct
Legacy ecommerce events	tr and ti	transaction and transaction_item

User fields#

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.

Payload property	Field name	Type	Description	Reqd?	Example	Source	Web	Mobile
uid	user_id	text	Unique identifier for user, set by the business using setUserId	No	c94f860b-1266-4dad-ae57-3a36a414a521	Tracking	✅	✅
duid	domain_userid	text	Unique identifier for a user, based on a first party cookie	No	4b0dfa75-9a8c-46a1-9691-01add9db4200	Tracking	✅	❌
tnuid	network_userid	text	User ID set by Snowplow using server-set cookie	No	ecdff4d0-9175-40ac-a8bb-325c49733607	Tracking or pipeline	✅	✅
sid	domain_sessionid	text	Unique identifier (UUID) for this visit of this domain_userid to this domain	No	c6ef3124-b53a-4b13-a233-0088f79dcbcb	Tracking	✅	❌
vid	domain_sessionidx	int	Index of number of visits that this domain_userid has made to this domain	No	3	Tracking	✅	❌
ip	user_ipaddress	text	User IP address, can be overwritten with the IP anonymization enrichment	No	92.231.54.234	Tracking 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 property	Field name	Type	Description	Reqd?	Example	Source	Web	Mobile
aid	app_id	text	Application ID	Yes	snow-game-android	Tracking	✅	✅
p	platform	text	Platform the app runs on	Yes	web	Tracking	✅	✅
tna	name_tracker	text	Tracker namespace	No	tracker_1	Tracking	✅	✅

This table shows the possible values for the platform field:

Platform	platform value
Web, including mobile web	web
Mobile, tablet	mob
Desktop, laptop	pc
Server-side application	srv
General application	app
Connected TV	tv
Games console	cnsl
Internet of Things	iot

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.

To set the os_timezone timezone field, use the timezone plugin on web trackers, or set the timezone in the mobile tracker configuration.

Payload property	Field name	Type	Description	Reqd?	Example	Source	Web	Mobile
	collector_tstamp	timestamp	Timestamp for the event recorded by the Collector	Yes	2013-11-26 00:02:05.123	Pipeline	✅	✅
dtm	dvce_created_tstamp	timestamp	Timestamp for the event recorded on the client device	No	2013-11-26 00:03:57.885	Tracking	✅	✅
stm	dvce_sent_tstamp	timestamp	Timestamp when event occurred, as recorded by client device	No	2013-11-26 00:03:58.032	Tracking	✅	✅
	etl_tstamp	timestamp	Timestamp for when the event was validated and enriched	No	2017-01-26 00:01:25.292	Pipeline	✅	✅
	derived_tstamp	timestamp	Timestamp making allowance for inaccurate device clock	No	2013-11-26 00:02:04.123	Default enrichment	✅	✅
ttm	true_tstamp	timestamp	User-set "true timestamp" for the event	No	2013-11-26 00:02:04.123	Tracking	✅	✅
	load_tstamp	timestamp	Timestamp for when the data was loaded into the warehouse	No	2013-11-26 00:02:04.123	Pipeline	✅	✅
tz	os_timezone	text	Client operating system timezone	No	Europe/London	Tracking	✅	✅

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 and operating system 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 property	Field name	Type	Description	Reqd?	Example	Source	Web	Mobile
ua	useragent	text	Raw useragent	No	Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:105.0) Gecko/20100101 Firefox/105.0	Tracking or pipeline	✅	✅
res	dvce_screenheight	int	Screen height in pixels	No	1024	Tracking	✅	✅
res	dvce_screenwidth	int	Screen width in pixels	No	1900	Tracking	✅	✅

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

IP address fields#

These fields are populated by the IP enrichment.

Field name	Type	Description	Reqd?	Example	Source	Web	Mobile
ip_isp	text	User's ISP	No	FDN Communications	IP enrichment	✅	✅
ip_organization	text	Organization associated with the user's IP address - defaults to ISP name if none is found	No	Bouygues Telecom	IP enrichment	✅	✅
ip_domain	text	Second level domain name associated with the user's IP address	No	nuvox.net	IP enrichment	✅	✅
ip_netspeed	text	User's connection type	No	Cable/DSL	IP enrichment	✅	✅

Location fields#

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

Field name	Type	Description	Reqd?	Example	Source	Web	Mobile
geo_country	text	ISO 3166-1 code for the country the user is located in	No	GB, US	IP enrichment	✅	✅
geo_region	text	ISO-3166-2 code for country region the user is in	No	I9, TX	IP enrichment	✅	✅
geo_city	text	City the user is in	No	New York, London	IP enrichment	✅	✅
geo_zipcode	text	Postcode the user is in	No	94109	IP enrichment	✅	✅
geo_latitude	text	User location latitude	No	37.443604	IP enrichment	✅	✅
geo_longitude	text	User location longitude	No	-122.4124	IP enrichment	✅	✅
geo_region_name	text	User region name	No	Florida	IP enrichment	✅	✅
geo_timezone	text	User timezone name	No	Europe/London	IP 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 name	Type	Description	Reqd?	Example	Source	Web	Mobile
mkt_medium	text	Type of traffic source	No	'cpc', 'affiliate', 'organic', 'social'	Campaign attribution enrichment	✅	✅
mkt_source	text	The company or website where the traffic came from	No	'Google', 'Facebook'	Campaign attribution enrichment	✅	✅
mkt_term	text	Any keywords associated with the referrer	No	'new age tarot decks'	Campaign attribution enrichment	✅	✅
mkt_content	text	The content of the ad, or an ID so that it can be looked up	No	13894723	Campaign attribution enrichment	✅	✅
mkt_campaign	text	The campaign ID	No	'diageo-123'	Campaign attribution enrichment	✅	✅
mkt_clickid	text	The click ID	No	'ac3d8e459'	Campaign attribution enrichment	✅	✅
mkt_network	text	The ad network to which the click ID belongs	No	'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 property	Field name	Type	Description	Reqd?	Example	Source	Web	Mobile
	refr_domain_userid	text	The Snowplow domain_userid of the referring website	No	bc2e92ec6c204a14	Default enrichment	✅	✅
	refr_dvce_tstamp	timestamp	The time of attaching the domain_userid to the inbound link	No	2013-11-26 00:02:05	Default enrichment	✅	✅

Snowplow versions fields#

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

Payload property	Field name	Type	Description	Reqd?	Example	Source	Web	Mobile
tv	v_tracker	text	Tracker version	Yes	js-3.0.0	Tracking	✅	✅
	v_collector	text	Collector version	Yes	ssc-2.1.0-kinesis	Pipeline	✅	✅
	v_etl	text	ETL application versions	Yes	snowplow-micro-1.1.0-common-1.4.2	Default enrichment	✅	✅

Web-specific fields#

These fields apply only to events from web.

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 property	Field name	Type	Description	Reqd?	Example	Source	Web	Mobile
url	page_url	text	The page URL	No	https://www.snowplow.io/product/index.html?id=GTM-DLRG#conclusion	Tracking	✅	❌
	page_urlscheme	text	Scheme, also known as protocol	No	https	Default enrichment	✅	❌
	page_urlhost	text	Host, also known as domain	No	www.snowplow.io	Default enrichment	✅	❌
	page_urlport	int	Port if specified, scheme dependent if not; 443 for HTTPS, 80 for HTTP	No	443	Default enrichment	✅	❌
	page_urlpath	text	Path to page	No	/product/index.html	Default enrichment	✅	❌
	page_urlquery	text	Querystring	No	id=GTM-DLRG	Default enrichment	✅	❌
	page_urlfragment	text	Fragment, also known as anchor	No	conclusion	Default enrichment	✅	❌
page	page_title	text	Web page title	No	Snowplow Behavioral Data	Tracking	✅	❌
refr	page_referrer	text	URL of the referrer	No	https://www.google.com/search?q=psychic+oracle+cards	Tracking	✅	❌
	refr_urlscheme	text	Referrer scheme	No	https	Default enrichment	✅	❌
	refr_urlhost	text	Referrer host	No	www.google.com	Default enrichment	✅	❌
	refr_urlport	int	Referrer port	No	443	Default enrichment	✅	❌
	refr_urlpath	text	Referrer page path	No	/search	Default enrichment	✅	❌
	refr_urlquery	text	Referrer URL querystring	No	q=psychic+oracle+cards	Default enrichment	✅	❌
	refr_urlfragment	text	Referrer URL fragment	No		Default enrichment	✅	❌
	refr_medium	text	Type of referrer	No	search', 'internal	Referrer parser enrichment	✅	❌
	refr_source	text	Name of referrer if recognized	No	Google	Referrer parser enrichment	✅	❌
	refr_term	text	Keywords if source is a search engine	No	psychic oracle cards	Referrer 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 property	Field name	Type	Description	Reqd?	Example	Source	Web	Mobile
cs	doc_charset	text	The page's character encoding	No	UTF-8	Tracking	✅	❌
ds	doc_width	int	The page's width in pixels	No	1024	Tracking	✅	❌
ds	doc_height	int	The page's height in pixels	No	3000	Tracking	✅	❌

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 property	Field name	Type	Description	Reqd?	Example	Source	Web	Mobile
lang	br_lang	text	Language the browser is set to	No	en-GB	Tracking	✅	❌
cookie	br_cookies	boolean	Whether the browser is accepting cookies	No	1	Tracking	✅	❌
cd	br_colordepth	int	Bit depth of the browser color palette	No	24	Tracking	✅	❌
vp	br_viewwidth	int	Viewport width	No	1000	Tracking	✅	❌
vp	br_viewheight	int	Viewport height	No	1000	Tracking	✅	❌

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

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 property	Field name	Type	Description	Reqd?	Example
pp_mix	pp_xoffset_min	int	Minimum page x offset seen in the last ping period	No	10
pp_max	pp_xoffset_max	int	Maximum page x offset seen in the last ping period	No	100
pp_miy	pp_yoffset_min	int	Minimum page y offset seen in the last ping period	No	5
pp_may	pp_yoffset_max	int	Maximum page y offset seen in the last ping period	No	200

Structured events#

Structured events use these fields to capture event data:

Payload property	Field name	Type	Description	Reqd?	Example
se_ca	se_category	text	Category of event	Yes *	ecomm, video
se_ac	se_action	text	Action performed, or event name	Yes *	add-to-basket, play-video
se_la	se_label	text	The object of the action e.g. the ID of the video played. or SKU of the product added to basket	No	pbz00123
se_pr	se_property	text	A property associated with the object of the action	No	HD, large
se_va	se_value	decimal	A value associated with the event or action e.g. the value of goods added-to-basket	No	9.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 name	Type	Description	Reqd?	Example	Source	Web	Mobile
event_vendor	text	Business that defined the event	Yes	com.acme	Default enrichment	✅	✅
event_name	text	Event name	Yes	link_click	Default enrichment	✅	✅
event_format	text	Format for event; always jsonschema	Yes	jsonschema	Default enrichment	✅	✅
event_version	text	Version of event schema	Yes	1-0-2	Default 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 name	Type	Description	Reqd?	Example	Source	Web	Mobile
txn_id	int	Transaction ID set client-side, used to de-dupe records	No	421828	Deprecated	✅	✅
dvce_type	text	Type of device	No	Computer	Deprecated	✅	✅
dvce_ismobile	boolean	Is the device mobile?	No	1	Deprecated	✅	✅
os_name	text	Name of operating system	No	Android	Deprecated	✅	✅
os_family	text	Operating system family	No	Linux	Deprecated	✅	✅
os_manufacturer	text	Company responsible for OS	No	Apple	Deprecated	✅	✅
user_fingerprint	int	A user fingerprint generated by looking at the individual browser features	No	2161814971	Deprecated	❌	❌
br_name	text	Browser name	No	Firefox 12	Deprecated	❌	❌
br_version	text	Browser version	No	12.0	Deprecated	❌	❌
br_family	text	Browser family	No	Firefox	Deprecated	❌	❌
br_type	text	Browser type	No	Browser	Deprecated	❌	❌
br_renderengine	text	Browser rendering engine	No	GECKO	Deprecated	❌	❌
br_features_pdf	boolean	Whether the browser recognizes PDFs	No	1	Deprecated	✅	❌
br_features_flash	boolean	Whether Flash is installed	No	1	Deprecated	✅	❌
br_features_java	boolean	Whether Java is installed	No	1	Deprecated	✅	❌
br_features_director	boolean	Whether Adobe Shockwave is installed	No	1	Deprecated	✅	❌
br_features_quicktime	boolean	Whether QuickTime is installed	No	1	Deprecated	✅	❌
br_features_realplayer	boolean	Whether RealPlayer is installed	No	1	Deprecated	✅	❌
br_features_windowsmedia	boolean	Whether mplayer2 is installed	No	1	Deprecated	✅	❌
br_features_gears	boolean	Whether Google Gears is installed	No	1	Deprecated	✅	❌
br_features_silverlight	boolean	Whether Microsoft Silverlight is installed	No	1	Deprecated	✅	❌

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 name	Type	Description	Reqd?	Example
tr_orderid	text	Order ID	Yes	#134
tr_affiliation	text	Transaction affiliation (e.g. store where sale took place)	No	web
tr_total	decimal	Total transaction value	Yes	12.99
tr_tax	decimal	Total tax included in transaction value	No	3.00
tr_shipping	decimal	Delivery cost charged	No	0.00
tr_total_base *	decimal	Total in base currency	No	12.99
tr_tax_base *	decimal	Total tax in base currency	No	3.00
tr_shipping_base *	decimal	Delivery cost in base currency	No	0.00
tr_city	text	Delivery address, city	No	London
tr_state	text	Delivery address, state	No	Washington
tr_country	text	Delivery address, country	No	France
tr_currency	text	Currency	No	USD
ti_orderid	text	Order ID	Yes	#134
ti_sku	text	Product SKU	Yes	pbz00123
ti_name	text	Product name	No	Cone pendulum
ti_category	text	Product category	No	New Age
ti_price	decimal	Product unit price	Yes	9.99
ti_price_base *	decimal	Price in base currency	No	9.99
ti_quantity	int	Number of product in transaction	Yes	2
ti_currency	text	Currency	No	EUR
base_currency *	text	Reporting currency	No	GBP

* Set exclusively by the Currency conversion enrichment.