Snowplow
Snowplow is a behavioral data platform for collecting
and routing event data. The destination sends events via the browser tracker,
supporting both the npm @snowplow/browser-tracker and the JavaScript tracker
(sp.js). walkerOS handles tracker initialization, plugin loading, activity
tracking (page pings), and self-describing ecommerce events with context
entities.
Snowplow is a web destination in the walkerOS flow:
Installation
The destination supports two tracking approaches:
- JavaScript tag (sp.js): loads the Snowplow tracker script from CDN
- npm packages: uses
@snowplow/browser-trackerfor smaller bundles and tree-shaking (see npm tracker)
With loadScript: true, the destination loads the Snowplow tracker script
(sp.js).
npm install @walkeros/collector @walkeros/web-destination-snowplow- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import destinationSnowplow from '@walkeros/web-destination-snowplow';
await startFlow({
destinations: {
snowplow: {
code: destinationSnowplow,
config: {
loadScript: true,
settings: {
collectorUrl: 'https://collector.example.com',
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "web"
},
"destinations": {
"snowplow": {
"package": "@walkeros/web-destination-snowplow",
"config": {
"loadScript": true,
"settings": {
"collectorUrl": "https://collector.example.com"
}
}
}
}
}
}
}The quickstart above sends no event yet. Every event needs a rule: its name is
the action type of the self-describing event (like add_to_cart for the
ecommerce action schema). An event that no rule maps, and that is not the
pageViewEvent, fails with missing-input; add an ignore: true rule for
events you do not send. To send page views, add pageViewEvent: 'page view' to
settings, as the package README's quick start does.
The quickstart also sets no consent, so sp.js loads and its tracker starts
without analytics consent, every event you map is sent without it, and a
revocation changes nothing. Add consent: { analytics: true } to config, next
to settings, before you go live (see gate a destination).
npm tracker
Uses imported functions directly: smaller bundles through tree-shaking, and type-safe calls.
Available packages and functions:
| Package | Functions | Purpose |
|---|---|---|
@snowplow/browser-tracker | newTracker, trackSelfDescribingEvent | Core tracking (required) |
@snowplow/browser-tracker | trackPageView | trackPageView and pageViewEvent |
@snowplow/browser-tracker | trackStructEvent | Rules with struct |
@snowplow/browser-tracker | setUserId | userId |
@snowplow/browser-tracker | enableActivityTracking, disableActivityTracking | activityTracking; without disableActivityTracking a consent revocation fails with consent-not-applied |
@snowplow/browser-tracker | addPlugin, addGlobalContexts | plugins, globalContexts |
@snowplow/browser-plugin-snowplow-ecommerce | SnowplowEcommercePlugin, setPageType | Ecommerce tracking, page |
Pass every function your settings and rules use: a call whose function is
missing is skipped and the event still counts as delivered (a struct rule
without trackStructEvent sends nothing). A plugin in
plugins is added with addPlugin; give a plugin factory a config (an empty
object when it takes none), because without one the destination adds the
factory itself and the plugin never starts. The destination cannot call a
plugin's enable function, such as enableLinkClickTracking, in this mode:
call it yourself, or use sp.js with a URL plugin. A plugin you enable yourself
keeps sending after a consent revocation until you disable it. Consent tracking
(settings.consent) and the runtime privacy controls below work only with
sp.js.
- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import { destinationSnowplow } from '@walkeros/web-destination-snowplow';
import {
newTracker,
trackSelfDescribingEvent,
trackPageView,
enableActivityTracking,
addPlugin,
addGlobalContexts,
} from '@snowplow/browser-tracker';
import {
SnowplowEcommercePlugin,
setPageType,
} from '@snowplow/browser-plugin-snowplow-ecommerce';
const { elb } = await startFlow({
destinations: {
snowplow: {
code: destinationSnowplow,
config: {
settings: {
tracker: {
newTracker,
trackSelfDescribingEvent,
trackPageView,
enableActivityTracking,
addPlugin,
addGlobalContexts,
setPageType,
},
collectorUrl: 'https://collector.example.com',
appId: 'my-app',
plugins: [{ code: SnowplowEcommercePlugin, config: {} }],
},
},
},
},
});{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "web",
"bundle": {
"packages": {
"@snowplow/browser-tracker": {
"version": "^4",
"imports": [
"newTracker",
"trackSelfDescribingEvent",
"trackPageView",
"enableActivityTracking",
"addPlugin",
"addGlobalContexts"
]
},
"@snowplow/browser-plugin-snowplow-ecommerce": {
"version": "^4",
"imports": ["SnowplowEcommercePlugin", "setPageType"]
}
}
}
},
"destinations": {
"snowplow": {
"package": "@walkeros/web-destination-snowplow",
"config": {
"settings": {
"tracker": {
"newTracker": "$code:newTracker",
"trackSelfDescribingEvent": "$code:trackSelfDescribingEvent",
"trackPageView": "$code:trackPageView",
"enableActivityTracking": "$code:enableActivityTracking",
"addPlugin": "$code:addPlugin",
"addGlobalContexts": "$code:addGlobalContexts",
"setPageType": "$code:setPageType"
},
"collectorUrl": "https://collector.example.com",
"appId": "my-app",
"plugins": [
{ "code": "$code:SnowplowEcommercePlugin", "config": {} }
]
}
}
}
}
}
}
}See bundled mode setup | CLI reference
Configuration
This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.
Settings
| Property | Type | Description | More |
|---|---|---|---|
collectorUrl | string | Snowplow collector endpoint URL | |
scriptUrl | string | URL of the Snowplow JavaScript tracker script, used with loadScript. Defaults to the jsdelivr CDN with the @latest tag; pin a version in production. | |
tracker | Record<string, any> | Browser-tracker functions for bundled mode (newTracker, trackSelfDescribingEvent and the optional others), set with $code: references | |
appId | string | Application identifier, sent as app_id with every event. Default: walkerOS. | |
trackerName | string | Tracker instance name | |
platform | string | Platform identifier | |
snowplow | snowplow | Snowplow-specific ecommerce configuration | |
actionSchema | string | Ecommerce action schema URI | |
productSchema | string | Product entity schema URI | |
cartSchema | string | Cart entity schema URI | |
transactionSchema | string | Transaction entity schema URI | |
refundSchema | string | Refund entity schema URI | |
checkoutStepSchema | string | Checkout step entity schema URI | |
promotionSchema | string | Promotion entity schema URI | |
userSchema | string | User entity schema URI | |
customSchemas | Record<string, string> | Custom entity schemas | |
currency | string | Default currency code (ISO 4217) | |
discoverRootDomain | boolean | Discover root domain for cookies | |
cookieSameSite | 'Strict' | 'Lax' | 'None' | Cookie SameSite attribute | |
appVersion | string | Application version | |
contexts | contexts | Built-in context entities | |
webPage | boolean | Web page context | |
session | boolean | Client session context - enables client_session schema | |
browser | boolean | Browser context | |
performanceTiming | boolean | Performance timing context | |
geolocation | boolean | Geolocation context | |
anonymousTracking | boolean | object | Enable anonymous tracking (no user identifiers) | |
plugins | Array<any> | Snowplow plugins | |
activityTracking | activityTracking | Page ping configuration | |
minimumVisitLength | number | Seconds before first ping | |
heartbeatDelay | number | Seconds between pings | |
globalContexts | Array<any> | Global context entities | |
trackPageView | boolean | Call trackPageView once right after the tracker starts | |
pageViewEvent | string | Event name that calls trackPageView instead of a self-describing event | |
userId | any | walkerOS mapping value resolving to the user id, set once on the first event where it resolves | |
page | page | Page context for setPageType (ecommerce plugin) | |
type | any | Mapping value resolving to the page type | |
language | any | Mapping value resolving to the page language | |
locale | any | Mapping value resolving to the page locale | |
consent | consent | Consent event tracking through the Enhanced Consent plugin, used by the consent handler | |
required | Array<string> | walkerOS consent groups to check | |
basisForProcessing | string | Legal basis for processing under GDPR (default consent) | |
consentUrl | string | URL of the privacy policy or consent document | |
consentVersion | string | Version of the consent document | |
domainsApplied | Array<string> | Domains where this consent applies | |
gdprApplies | boolean | Whether GDPR applies to this user |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
context | Array<object> | Context entities to attach to this event | |
snowplow | snowplow | Snowplow-specific settings override | |
actionSchema | string | Override action schema for this specific event | |
data | any | Mapping value with a map resolving to the self-describing event data | |
struct | struct | Send a structured event with trackStructEvent instead of a self-describing event; category and action must resolve to strings | |
category | any | Mapping value resolving to the category | |
action | any | Mapping value resolving to the action | |
label | any | Mapping value resolving to the label | |
property | any | Mapping value resolving to the property | |
value | any | Mapping value resolving to a number |
Examples
Add to cart
A product add fires a Snowplow ecommerce add_to_cart action with product, cart, page, and user contexts.
{
"name": "product add",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420,
"quantity": 1,
"currency": "EUR"
},
"context": {
"shopping": [
"intent",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [],
"consent": {
"functional": true
},
"id": "83e860384d50953f",
"trigger": "click",
"entity": "product",
"action": "add",
"timestamp": 1700000401000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "add_to_cart",
"settings": {
"context": [
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/product/jsonschema/1-0-0",
"data": {
"id": "data.id",
"name": "data.name",
"category": "data.category",
"price": "data.price",
"currency": {
"key": "data.currency",
"value": "USD"
},
"quantity": {
"key": "data.quantity",
"value": 1
}
}
},
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/cart/jsonschema/1-0-0",
"data": {
"total_value": "globals.cart_value",
"currency": [
"data.currency",
"globals.cart_currency"
]
}
},
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/page/jsonschema/1-0-0",
"data": {
"type": "globals.page_type",
"language": "globals.language"
}
},
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/user/jsonschema/1-0-0",
"data": {
"id": "user.id",
"email": "user.email",
"is_guest": {
"fn": {
"$code": "e=>{var o;return!!(null==(o=e.user)?void 0:o.id)||void 0}"
}
}
}
}
]
}
}snowplow.trackSelfDescribingEvent({
"event": {
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/snowplow_ecommerce_action/jsonschema/1-0-2",
"data": {
"type": "add_to_cart"
}
},
"context": [
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/product/jsonschema/1-0-0",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"price": 420,
"currency": "EUR",
"quantity": 1
}
},
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/cart/jsonschema/1-0-0",
"data": {
"currency": "EUR"
}
},
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/page/jsonschema/1-0-0",
"data": {}
},
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/user/jsonschema/1-0-0",
"data": {
"id": "us3r",
"is_guest": true
}
}
]
})Checkout step
A checkout start fires a Snowplow checkout_step action with the checkout step, 1 when the event carries none.
{
"name": "checkout start",
"data": {
"currency": "EUR",
"value": 462
},
"context": {
"shopping": [
"checkout",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "product",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420
},
"context": {
"shopping": [
"checkout",
0
]
},
"nested": []
},
{
"entity": "product",
"data": {
"id": "cc",
"name": "Cool Cap",
"size": "one size",
"price": 42
},
"context": {
"shopping": [
"checkout",
0
]
},
"nested": []
}
],
"consent": {
"functional": true
},
"id": "b69962a4930657f9",
"trigger": "load",
"entity": "checkout",
"action": "start",
"timestamp": 1700000405000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "checkout_step",
"settings": {
"context": [
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/checkout_step/jsonschema/1-0-0",
"data": {
"step": {
"key": "data.step",
"value": 1
},
"option": "data.option"
}
}
]
}
}snowplow.trackSelfDescribingEvent({
"event": {
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/snowplow_ecommerce_action/jsonschema/1-0-2",
"data": {
"type": "checkout_step"
}
},
"context": [
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/checkout_step/jsonschema/1-0-0",
"data": {
"step": 1
}
}
]
})Transaction with products
A transaction event adds one Snowplow product context per nested product via a loop mapping.
{
"name": "order complete",
"data": {
"id": "0rd3r1d",
"currency": "EUR",
"value": 462,
"tax": 73.76,
"shipping": 5.22,
"total": 467.22
},
"context": {
"shopping": [
"complete",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "product",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
},
{
"entity": "product",
"data": {
"id": "cc",
"name": "Cool Cap",
"size": "one size",
"price": 42
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
},
{
"entity": "gift",
"data": {
"name": "Surprise"
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
}
],
"consent": {
"functional": true
},
"id": "235d0d7bd7a213f2",
"trigger": "load",
"entity": "order",
"action": "complete",
"timestamp": 1700000407000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "transaction",
"settings": {
"context": [
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/transaction/jsonschema/1-0-0",
"data": {
"transaction_id": "data.id",
"revenue": [
"data.total",
"data.value"
],
"currency": "data.currency"
}
},
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/product/jsonschema/1-0-0",
"data": {
"loop": [
"nested",
{
"map": {
"id": "data.id",
"name": "data.name",
"price": "data.price"
}
}
]
}
}
]
}
}snowplow.trackSelfDescribingEvent({
"event": {
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/snowplow_ecommerce_action/jsonschema/1-0-2",
"data": {
"type": "transaction"
}
},
"context": [
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/transaction/jsonschema/1-0-0",
"data": {
"transaction_id": "0rd3r1d",
"revenue": 467.22,
"currency": "EUR"
}
},
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/product/jsonschema/1-0-0",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"price": 420
}
},
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/product/jsonschema/1-0-0",
"data": {
"id": "cc",
"name": "Cool Cap",
"price": 42
}
},
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/product/jsonschema/1-0-0",
"data": {
"name": "Surprise"
}
}
]
})Initialization
Destination bootstrap creates a Snowplow tracker pointed at the configured collector URL.
{
"loadScript": true,
"settings": {
"collectorUrl": "https://collector.example.com",
"appId": "my-app",
"pageViewEvent": "page view"
}
}snowplow.newTracker("sp", "https://collector.example.com", {
"appId": "my-app",
"platform": "web"
})Page view
A page view calls Snowplow trackPageView directly instead of a self-describing event.
{
"name": "page view",
"data": {
"domain": "www.example.com",
"title": "walkerOS documentation",
"referrer": "https://www.walkeros.io/",
"search": "?foo=bar",
"hash": "#hash",
"id": "/docs/"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"pagegroup": "docs"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "f0cc5f6fec3d8eeb",
"trigger": "load",
"entity": "page",
"action": "view",
"timestamp": 1700000404000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}snowplow.trackPageView()Product view
A product view fires a Snowplow ecommerce action with a product context schema and pricing fields.
{
"name": "product view",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420,
"currency": "EUR"
},
"context": {
"shopping": [
"detail",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [],
"consent": {
"functional": true
},
"id": "db22fb16c70f663d",
"trigger": "load",
"entity": "product",
"action": "view",
"timestamp": 1700000400000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "product_view",
"settings": {
"context": [
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/product/jsonschema/1-0-0",
"data": {
"id": "data.id",
"name": "data.name",
"category": "data.category",
"price": "data.price",
"currency": {
"key": "data.currency",
"value": "USD"
},
"brand": "data.brand",
"variant": "data.variant"
}
}
]
}
}snowplow.trackSelfDescribingEvent({
"event": {
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/snowplow_ecommerce_action/jsonschema/1-0-2",
"data": {
"type": "product_view"
}
},
"context": [
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/product/jsonschema/1-0-0",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"price": 420,
"currency": "EUR"
}
}
]
})Promo view
A promotion visible event fires a Snowplow promo_view action with a promotion context.
{
"name": "promotion visible",
"data": {
"id": "promo_autumn26",
"name": "Setting up tracking easily",
"slot": "hero"
},
"context": {
"ab_test": [
"engagement",
0
]
},
"globals": {
"pagegroup": "homepage"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "1264bd65afd24f10",
"trigger": "visible",
"entity": "promotion",
"action": "visible",
"timestamp": 1700000403000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "promo_view",
"settings": {
"context": [
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/promotion/jsonschema/1-0-0",
"data": {
"id": "data.id",
"name": "data.name",
"creative_id": "data.creative_id",
"type": "data.type",
"position": "data.position",
"slot": "data.slot"
}
}
]
}
}snowplow.trackSelfDescribingEvent({
"event": {
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/snowplow_ecommerce_action/jsonschema/1-0-2",
"data": {
"type": "promo_view"
}
},
"context": [
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/promotion/jsonschema/1-0-0",
"data": {
"id": "promo_autumn26",
"name": "Setting up tracking easily",
"slot": "hero"
}
}
]
})Struct event
A custom event is tracked via Snowplow trackStructEvent with category, action, label, property, and value.
{
"name": "product visible",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420,
"position": 3,
"list": "Related products",
"promo": true
},
"context": {
"shopping": [
"discover",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [],
"consent": {
"functional": true
},
"id": "f68f1601a5c2b586",
"trigger": "load",
"entity": "product",
"action": "visible",
"timestamp": 1700000406000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"settings": {
"struct": {
"category": {
"value": "ecommerce"
},
"action": {
"value": "impression"
},
"label": "data.name",
"property": "data.color",
"value": "data.price"
}
}
}snowplow.trackStructEvent({
"category": "ecommerce",
"action": "impression",
"label": "Everyday Ruck Snack",
"property": "black",
"value": 420
})Transaction
A completed order fires a Snowplow ecommerce transaction action with transaction id, revenue, tax, and shipping.
{
"name": "order complete",
"data": {
"id": "0rd3r1d",
"currency": "EUR",
"value": 462,
"tax": 73.76,
"shipping": 5.22,
"total": 467.22
},
"context": {
"shopping": [
"complete",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "product",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
},
{
"entity": "product",
"data": {
"id": "cc",
"name": "Cool Cap",
"size": "one size",
"price": 42
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
},
{
"entity": "gift",
"data": {
"name": "Surprise"
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
}
],
"consent": {
"functional": true
},
"id": "235d0d7bd7a213f2",
"trigger": "load",
"entity": "order",
"action": "complete",
"timestamp": 1700000402000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "transaction",
"settings": {
"context": [
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/transaction/jsonschema/1-0-0",
"data": {
"transaction_id": "data.id",
"revenue": [
"data.total",
"data.value"
],
"currency": {
"key": "data.currency",
"value": "USD"
},
"payment_method": {
"value": "credit_card"
},
"tax": "data.tax",
"shipping": "data.shipping"
}
}
]
}
}snowplow.trackSelfDescribingEvent({
"event": {
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/snowplow_ecommerce_action/jsonschema/1-0-2",
"data": {
"type": "transaction"
}
},
"context": [
{
"schema": "iglu:com.snowplowanalytics.snowplow.ecommerce/transaction/jsonschema/1-0-0",
"data": {
"transaction_id": "0rd3r1d",
"revenue": 467.22,
"currency": "EUR",
"payment_method": "credit_card",
"tax": 73.76,
"shipping": 5.22
}
}
]
})settings.collectorUrl is required and the settings schema is closed, so walkeros validate rejects a key Snowplow does not read. The Snowplow script is injected once per script URL; if it fails to load, later events fail visibly. If your page already loads sp.js, leave loadScript off, or the script loads twice.
User identity and privacy
Cross-session user stitching
Use userId to link events across sessions when users log in. The ID is set
once via Snowplow's setUserId() on the first event where the value resolves:
{
collectorUrl: 'https://collector.example.com',
userId: 'user.id',
}The userId setting supports walkerOS mapping syntax:
'user.id'from walkerOS user object (recommended)'globals.user_id'from globals
Anonymous tracking
Enable anonymous tracking for privacy-focused collection or before consent:
{
collectorUrl: 'https://collector.example.com',
anonymousTracking: {
withServerAnonymisation: true,
withSessionTracking: true,
},
}Runtime privacy controls
Control tracking modes at runtime using exported utility functions. They call
the sp.js tracker (window.snowplow) and do nothing with settings.tracker;
there, call the browser tracker's own functions of the same name:
import {
clearUserData,
enableAnonymousTracking,
disableAnonymousTracking,
} from '@walkeros/web-destination-snowplow';
clearUserData();
enableAnonymousTracking({ withServerAnonymisation: true });
disableAnonymousTracking();Consent revocation
On a revocation of the destination's required consent (config.consent),
activity tracking and the sp.js URL plugins for link, form, button and YouTube
tracking are switched off, and a grant switches them back on. The error
tracking and FocalMeter URL plugins have no off switch, so a revocation with
them enabled fails visibly (consent-not-applied). With settings.tracker,
only activityTracking follows consent: a plugin you enable yourself keeps
sending after a revocation until you disable it.
Consent tracking
Track GDPR/CCPA consent events using Snowplow's Enhanced Consent plugin.
With settings.consent, the destination reacts to walkerOS consent commands and
calls the matching Snowplow consent method. This works with sp.js only: with
settings.tracker, no consent event is sent.
Prerequisites: load the Enhanced Consent plugin via the plugins setting
or include it in your Snowplow script bundle.
{
collectorUrl: 'https://collector.example.com',
consent: {
required: ['analytics', 'marketing'],
basisForProcessing: 'consent',
consentUrl: 'https://example.com/privacy',
consentVersion: '2.0',
domainsApplied: ['example.com'],
gdprApplies: true,
},
}| Option | Type | Description |
|---|---|---|
required | string[] | walkerOS consent groups to check |
basisForProcessing | string | GDPR basis: consent, contract, legal_obligation, vital_interests, public_task, legitimate_interests |
consentUrl | string | Privacy policy URL |
consentVersion | string | Policy version |
domainsApplied | string[] | Domains where consent applies |
gdprApplies | boolean | Whether GDPR applies |
The destination decides on the keys of each consent command. A required scope
the command does not name counts as not granted, so a command that only revokes
marketing sends trackConsentDeny for analytics too:
| Required scopes in the consent command | Snowplow method |
|---|---|
| All granted | trackConsentAllow |
| None granted | trackConsentDeny |
| Some granted | trackConsentSelected |
Media tracking
Track video and audio playback events using Snowplow's media tracking schemas.
Each media event is a self-describing event with the media schema as its
actionSchema. Like every other event, it needs a rule with a name; the
event data comes from the rule's settings.data.
Basic usage
await elb({
name: 'video play',
data: {
id: 'video-123',
playbackId: 'playback-1',
title: 'Product Demo',
currentTime: 0,
duration: 120,
},
});
await elb({
name: 'video progress',
data: { id: 'video-123', playbackId: 'playback-1', percentProgress: 25 },
});
await elb({
name: 'video pause',
data: { id: 'video-123', playbackId: 'playback-1', currentTime: 45 },
});
await elb({
name: 'video end',
data: { id: 'video-123', playbackId: 'playback-1', duration: 120 },
});Media mapping configuration
Configure media event mappings with the MEDIA_SCHEMAS constants. Give every
media rule the SESSION entity with one mediaSessionId per playback:
Snowplow's media data model groups the events of a playback by this ID, and the
destination attaches only the entities a rule lists. Every event of the playback
must carry the ID (playbackId in the events above): an event without it is
still sent, with an empty SESSION entity that fails Snowplow's schema
validation. The MEDIA_PLAYER entity (media_player 1-0-0) requires
currentTime, duration, ended, loop, muted, paused, playbackRate
and volume:
import { MEDIA_SCHEMAS } from '@walkeros/web-destination-snowplow';
{
video: {
play: {
name: 'play',
settings: {
snowplow: { actionSchema: MEDIA_SCHEMAS.PLAY },
context: [{
schema: MEDIA_SCHEMAS.SESSION,
data: { mediaSessionId: 'data.playbackId' },
}, {
schema: MEDIA_SCHEMAS.MEDIA_PLAYER,
data: {
currentTime: 'data.currentTime',
duration: 'data.duration',
ended: { value: false },
loop: { value: false },
muted: { key: 'data.muted', value: false },
paused: { value: false },
playbackRate: { key: 'data.playbackRate', value: 1 },
volume: { key: 'data.volume', value: 100 },
},
}],
},
},
progress: {
name: 'percent_progress',
settings: {
snowplow: { actionSchema: MEDIA_SCHEMAS.PERCENT_PROGRESS },
data: { map: { percentProgress: 'data.percentProgress' } },
context: [{
schema: MEDIA_SCHEMAS.SESSION,
data: { mediaSessionId: 'data.playbackId' },
}],
},
},
pause: {
name: 'pause',
settings: {
snowplow: { actionSchema: MEDIA_SCHEMAS.PAUSE },
context: [{
schema: MEDIA_SCHEMAS.SESSION,
data: { mediaSessionId: 'data.playbackId' },
}],
},
},
end: {
name: 'end',
settings: {
snowplow: { actionSchema: MEDIA_SCHEMAS.END },
context: [{
schema: MEDIA_SCHEMAS.SESSION,
data: { mediaSessionId: 'data.playbackId' },
}],
},
},
},
}Ad tracking
Track video advertisements with pre-roll, mid-roll, and post-roll events. Ads
belong to the playback, so their rules carry the same SESSION entity:
import { MEDIA_SCHEMAS } from '@walkeros/web-destination-snowplow';
{
ad: {
break_start: {
name: 'ad_break_start',
settings: {
snowplow: { actionSchema: MEDIA_SCHEMAS.AD_BREAK_START },
context: [{
schema: MEDIA_SCHEMAS.SESSION,
data: { mediaSessionId: 'data.playbackId' },
}, {
schema: MEDIA_SCHEMAS.AD_BREAK,
data: {
breakId: 'data.breakId',
breakType: 'data.breakType',
startTime: 'data.startTime',
},
}],
},
},
start: {
name: 'ad_start',
settings: {
snowplow: { actionSchema: MEDIA_SCHEMAS.AD_START },
context: [{
schema: MEDIA_SCHEMAS.SESSION,
data: { mediaSessionId: 'data.playbackId' },
}, {
schema: MEDIA_SCHEMAS.AD,
data: {
adId: 'data.adId',
name: 'data.name',
duration: 'data.duration',
},
}],
},
},
},
}Available media schemas
| Schema | Description | Use case |
|---|---|---|
PLAY | Playback started | Video/audio play |
PAUSE | Playback paused | User pauses content |
END | Playback ended | Video/audio completed |
SEEK_START / SEEK_END | User seeking | Scrubbing timeline |
BUFFER_START / BUFFER_END | Buffering state | Loading content |
QUALITY_CHANGE | Video quality changed | Adaptive streaming |
FULLSCREEN_CHANGE | Fullscreen toggled | User interaction |
VOLUME_CHANGE | Volume changed | User adjustment |
PERCENT_PROGRESS | Progress milestone | 25%, 50%, 75% markers |
ERROR | Playback error | Error tracking |
AD_BREAK_START / AD_BREAK_END | Ad break | Pre/mid/post-roll |
AD_START / AD_COMPLETE / AD_SKIP | Individual ad | Ad impressions |
Schema constants
The package exports pre-defined Snowplow schema URIs for use in custom mappings:
import {
SCHEMAS,
ACTIONS,
WEB_SCHEMAS,
CONSENT_SCHEMAS,
MEDIA_SCHEMAS,
MEDIA_ACTIONS,
} from '@walkeros/web-destination-snowplow';
SCHEMAS.PRODUCT;
SCHEMAS.TRANSACTION;
ACTIONS.ADD_TO_CART;
ACTIONS.TRANSACTION;
WEB_SCHEMAS.LINK_CLICK;
WEB_SCHEMAS.SUBMIT_FORM;
WEB_SCHEMAS.SITE_SEARCH;
MEDIA_SCHEMAS.PLAY;
MEDIA_SCHEMAS.PAUSE;
MEDIA_SCHEMAS.AD_BREAK_START;
CONSENT_SCHEMAS.PREFERENCES;
CONSENT_SCHEMAS.GDPR;Advanced configuration
Tracker settings
{
collectorUrl: 'https://collector.example.com',
appId: 'my-app',
appVersion: '1.0.0',
discoverRootDomain: true,
cookieSameSite: 'Lax',
contexts: {
webPage: true,
session: true,
browser: true,
},
}Activity tracking (page pings)
{
collectorUrl: 'https://collector.example.com',
activityTracking: {
minimumVisitLength: 10,
heartbeatDelay: 30,
},
}Page view tracking
Snowplow's native trackPageView() can be triggered either on init or via a
walkerOS event. Both options require explicit configuration. If neither
trackPageView nor pageViewEvent is set, no automatic page view tracking
occurs.
{
collectorUrl: 'https://collector.example.com',
trackPageView: true,
}{
collectorUrl: 'https://collector.example.com',
pageViewEvent: 'page view',
}Plugins
Load Snowplow plugins for automatic tracking. The destination supports both
URL-based plugins (sp.js) and npm BrowserPlugin instances. URL plugins need
sp.js: with settings.tracker, a URL plugin fails init with a config
error.
{
collectorUrl: 'https://collector.example.com',
plugins: [
{
url: 'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-link-click-tracking@latest/dist/index.umd.min.js',
name: ['snowplowLinkClickTracking', 'LinkClickTrackingPlugin'],
options: { trackContent: true },
},
],
}The enable method is derived automatically from the plugin name
(LinkClickTrackingPlugin becomes enableLinkClickTracking). Override with
enableMethod if needed.
Global contexts
Attach context entities to all events. Supports static objects and dynamic generator functions:
{
collectorUrl: 'https://collector.example.com',
globalContexts: [
{
schema: 'iglu:com.example/app_info/jsonschema/1-0-0',
data: { version: '1.0.0', environment: 'production' },
},
() => ({
schema: 'iglu:com.example/consent/jsonschema/1-0-0',
data: {
advertising: document.cookie.includes('ads_consent=1'),
},
}),
],
}Testing with Snowplow Micro
Use Snowplow Micro for local development:
docker run -p 9090:9090 snowplow/snowplow-microConfigure the destination with collectorUrl: 'http://localhost:9090' and
view events at http://localhost:9090/micro/ui.