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, and event mapping.
Snowplow is a web destination in the walkerOS flow:
Initializes the Snowplow tracker, loads plugins, enables activity tracking (page pings), and sends self-describing events with ecommerce context entities.
Installation
Setup
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
- JavaScript Tag (sp.js)
- NPM Packages (browser-tracker)
Loads the Snowplow tracker script automatically. Simple setup, works everywhere.
- Integrated
- Bundled
Uses imported functions directly. Smaller bundles, tree-shaking, type-safe.
Available packages and functions:
| Package | Functions | Purpose |
|---|---|---|
@snowplow/browser-tracker | newTracker, trackSelfDescribingEvent | Core tracking (required) |
@snowplow/browser-tracker | trackPageView, trackStructEvent, setUserId, enableActivityTracking, addPlugin, addGlobalContexts, clearUserData, enableAnonymousTracking, disableAnonymousTracking | Optional features |
@snowplow/browser-plugin-snowplow-ecommerce | SnowplowEcommercePlugin, setPageType | Ecommerce tracking |
@snowplow/browser-plugin-link-click-tracking | LinkClickTrackingPlugin | Auto link tracking |
@snowplow/browser-plugin-button-click-tracking | ButtonClickTrackingPlugin | Auto button tracking |
@snowplow/browser-plugin-enhanced-consent | trackConsentAllow, trackConsentDeny, trackConsentSelected | Consent tracking |
- Integrated
- Bundled
See Bundled Mode setup → | CLI reference →
Configuration reference
| Property | Type | Description | More |
|---|---|---|---|
collectorUrl | string | Snowplow collector endpoint URL | |
appId | string | Application identifier | |
trackerName | string | Tracker instance name | |
platform | string | Platform identifier | |
pageViewTracking | boolean | Enable automatic page view tracking | |
snowplow | object | Snowplow-specific ecommerce configuration | |
discoverRootDomain | boolean | Discover root domain for cookies | |
cookieSameSite | 'Strict' | 'Lax' | 'None' | Cookie SameSite attribute | |
appVersion | string | Application version | |
contexts | object | Built-in context entities | |
anonymousTracking | boolean | object | Enable anonymous tracking (no user identifiers) | |
plugins | Array<any> | Snowplow plugins | |
activityTracking | object | Page ping configuration | |
globalContexts | Array<any> | Global context entities |
Example
Event Mapping
For custom event mapping (mapping.entity.action.settings):
| Property | Type | Description | More |
|---|---|---|---|
context | Array<object> | Context entities to attach to this event | |
snowplow | object | Snowplow-specific settings override |
User Identity & 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:
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:
Runtime Privacy Controls
Control tracking modes at runtime using exported utility functions:
Consent Tracking
Track GDPR/CCPA consent events using Snowplow's Enhanced Consent plugin. The destination automatically reacts to walkerOS consent events and calls the appropriate Snowplow consent methods.
Prerequisites: Load the Enhanced Consent plugin via the plugins setting or include it in your Snowplow script bundle.
| 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 maps walkerOS consent state to Snowplow methods:
| walkerOS Consent State | Snowplow Method |
|---|---|
| All required scopes granted | trackConsentAllow |
| All required scopes denied | trackConsentDeny |
| Partial consent (mixed) | trackConsentSelected |
Media Tracking
Track video and audio playback events using Snowplow's media tracking schemas. The destination supports all media events and contexts.
Basic Usage
Media Mapping Configuration
Configure media event mappings with the MEDIA_SCHEMAS constants:
Ad Tracking
Track video advertisements with pre-roll, mid-roll, and post-roll events:
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:
Advanced Configuration
Tracker Settings
Configure Snowplow tracker behavior including cookie settings and built-in contexts:
Activity Tracking (Page Pings)
Enable activity tracking to measure user engagement through page pings:
Page View Tracking
Configure how Snowplow's native trackPageView() is triggered:
Option 1: Auto-track on init
Option 2: Track via walkerOS event
Option 3: Custom event name
Both settings require explicit configuration - there is no implicit default. If neither trackPageView nor pageViewEvent is set, no automatic page view tracking occurs.
Plugins
Load Snowplow plugins for automatic tracking of links, buttons, and forms. Supports both URL-based plugins (sp.js) and npm BrowserPlugin instances:
The enable method is derived automatically from the plugin name (LinkClickTrackingPlugin → enableLinkClickTracking). Override with enableMethod if needed.
Global Contexts
Attach context entities to all events. Supports static objects and dynamic generator functions:
Full Replacement Example
Replace native Snowplow tracker calls with a single walkerOS configuration:
Mapping examples
The code examples are interactive. You can edit the code to generate your individual event mapping.
Learn more about Snowplow Ecommerce tracking.
Product View
Map your walkerOS event to get a Snowplow product_view ecommerce event with product context.
Add to Cart
Map your walkerOS event to get a Snowplow add_to_cart ecommerce event with product, cart, page, and user context entities.
Transaction
Map your walkerOS event to get a Snowplow transaction ecommerce event with transaction context.
Promotion Visible
Map your walkerOS event to get a Snowplow promo_view ecommerce event with promotion context.
Testing with Snowplow Micro
Use Snowplow Micro for local development:
Configure the destination with collectorUrl: 'http://localhost:9090' and view events at http://localhost:9090/micro/ui.