Skip to main content
Ask your AI

Snowplow

Web Source code Package

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.

Where this fits

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-tracker for 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
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',
        },
      },
    },
  },
});

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:

PackageFunctionsPurpose
@snowplow/browser-trackernewTracker, trackSelfDescribingEventCore tracking (required)
@snowplow/browser-trackertrackPageViewtrackPageView and pageViewEvent
@snowplow/browser-trackertrackStructEventRules with struct
@snowplow/browser-trackersetUserIduserId
@snowplow/browser-trackerenableActivityTracking, disableActivityTrackingactivityTracking; without disableActivityTracking a consent revocation fails with consent-not-applied
@snowplow/browser-trackeraddPlugin, addGlobalContextsplugins, globalContexts
@snowplow/browser-plugin-snowplow-ecommerceSnowplowEcommercePlugin, setPageTypeEcommerce 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.

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: {} }],
        },
      },
    },
  },
});

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​

PropertyTypeDescriptionMore
collectorUrl*stringSnowplow collector endpoint URL
scriptUrlstringURL of the Snowplow JavaScript tracker script, used with loadScript. Defaults to the jsdelivr CDN with the @latest tag; pin a version in production.
trackerRecord<string, any>Browser-tracker functions for bundled mode (newTracker, trackSelfDescribingEvent and the optional others), set with $code: references
appIdstringApplication identifier, sent as app_id with every event. Default: walkerOS.
trackerNamestringTracker instance name
platformstringPlatform identifier
snowplowsnowplowSnowplow-specific ecommerce configuration
actionSchemastringEcommerce action schema URI
productSchemastringProduct entity schema URI
cartSchemastringCart entity schema URI
transactionSchemastringTransaction entity schema URI
refundSchemastringRefund entity schema URI
checkoutStepSchemastringCheckout step entity schema URI
promotionSchemastringPromotion entity schema URI
userSchemastringUser entity schema URI
customSchemasRecord<string, string>Custom entity schemas
currencystringDefault currency code (ISO 4217)
discoverRootDomainbooleanDiscover root domain for cookies
cookieSameSite'Strict' | 'Lax' | 'None'Cookie SameSite attribute
appVersionstringApplication version
contextscontextsBuilt-in context entities
webPagebooleanWeb page context
sessionbooleanClient session context - enables client_session schema
browserbooleanBrowser context
performanceTimingbooleanPerformance timing context
geolocationbooleanGeolocation context
anonymousTrackingboolean | objectEnable anonymous tracking (no user identifiers)
pluginsArray<any>Snowplow plugins
activityTrackingactivityTrackingPage ping configuration
minimumVisitLength*numberSeconds before first ping
heartbeatDelay*numberSeconds between pings
globalContextsArray<any>Global context entities
trackPageViewbooleanCall trackPageView once right after the tracker starts
pageViewEventstringEvent name that calls trackPageView instead of a self-describing event
userIdanywalkerOS mapping value resolving to the user id, set once on the first event where it resolves
pagepagePage context for setPageType (ecommerce plugin)
type*anyMapping value resolving to the page type
languageanyMapping value resolving to the page language
localeanyMapping value resolving to the page locale
consentconsentConsent event tracking through the Enhanced Consent plugin, used by the consent handler
requiredArray<string>walkerOS consent groups to check
basisForProcessingstringLegal basis for processing under GDPR (default consent)
consentUrlstringURL of the privacy policy or consent document
consentVersionstringVersion of the consent document
domainsAppliedArray<string>Domains where this consent applies
gdprAppliesbooleanWhether GDPR applies to this user
* Required fields

Mapping​

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

PropertyTypeDescriptionMore
contextArray<object>Context entities to attach to this event
snowplowsnowplowSnowplow-specific settings override
actionSchemastringOverride action schema for this specific event
dataanyMapping value with a map resolving to the self-describing event data
structstructSend a structured event with trackStructEvent instead of a self-describing event; category and action must resolve to strings
category*anyMapping value resolving to the category
action*anyMapping value resolving to the action
labelanyMapping value resolving to the label
propertyanyMapping value resolving to the property
valueanyMapping value resolving to a number
* Required fields

Examples

Add to cart

A product add fires a Snowplow ecommerce add_to_cart action with product, cart, page, and user contexts.

Event
{
  "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"
  }
}
Mapping
{
  "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}"
            }
          }
        }
      }
    ]
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "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"
        }
      }
    ]
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "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"
              }
            }
          ]
        }
      }
    ]
  }
}
Out
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.

Event
{
  "loadScript": true,
  "settings": {
    "collectorUrl": "https://collector.example.com",
    "appId": "my-app",
    "pageViewEvent": "page view"
  }
}
Out
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.

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"
  }
}
Out
snowplow.trackPageView()

Product view

A product view fires a Snowplow ecommerce action with a product context schema and pricing fields.

Event
{
  "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"
  }
}
Mapping
{
  "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"
        }
      }
    ]
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "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"
        }
      }
    ]
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "settings": {
    "struct": {
      "category": {
        "value": "ecommerce"
      },
      "action": {
        "value": "impression"
      },
      "label": "data.name",
      "property": "data.color",
      "value": "data.price"
    }
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "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"
        }
      }
    ]
  }
}
Out
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();

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.

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,
  },
}
OptionTypeDescription
requiredstring[]walkerOS consent groups to check
basisForProcessingstringGDPR basis: consent, contract, legal_obligation, vital_interests, public_task, legitimate_interests
consentUrlstringPrivacy policy URL
consentVersionstringPolicy version
domainsAppliedstring[]Domains where consent applies
gdprAppliesbooleanWhether 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 commandSnowplow method
All grantedtrackConsentAllow
None grantedtrackConsentDeny
Some grantedtrackConsentSelected

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​

SchemaDescriptionUse case
PLAYPlayback startedVideo/audio play
PAUSEPlayback pausedUser pauses content
ENDPlayback endedVideo/audio completed
SEEK_START / SEEK_ENDUser seekingScrubbing timeline
BUFFER_START / BUFFER_ENDBuffering stateLoading content
QUALITY_CHANGEVideo quality changedAdaptive streaming
FULLSCREEN_CHANGEFullscreen toggledUser interaction
VOLUME_CHANGEVolume changedUser adjustment
PERCENT_PROGRESSProgress milestone25%, 50%, 75% markers
ERRORPlayback errorError tracking
AD_BREAK_START / AD_BREAK_ENDAd breakPre/mid/post-roll
AD_START / AD_COMPLETE / AD_SKIPIndividual adAd 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-micro

Configure the destination with collectorUrl: 'http://localhost:9090' and view events at http://localhost:9090/micro/ui.

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)