Skip to main content

Event model

A single event model to support analytics, marketing, privacy and data science needs.

Entity-Action Approach

The Entity-Action approach is the core of the walkerOS event model. It's a framework designed to capture interactions in a structured yet flexible manner. Two primary components define each event: the 'entity' (what is involved within an interaction) and the 'action' (what is done with the entity). This method provides a comprehensive and clear understanding of user behaviors and interactions.

One of the great things about walkerOS is the full flexibility of event definitions. You can build your tracking based on your business logic instead of trying to press your business logic into analytics specs.

We believe that tracking shouldn't sound like some abstract technical concept. It should feel natural and everyone involved should immediately understand it. Only when everyone understands what is being measured, there will be fewer misunderstandings, higher data quality, and more actionable data in the organization at the end of the day.

A walkerOS event consists of three components: a trigger (e.g. load), an entity (e.g. page), and an action (e.g. view).

Event Structure

Here's an example illustrating the structure and components of an event in walkerOS. While keys are static, their content can be defined dynamically with different value types.

event: 'promotion view', // Name as a combination of entity and action
data: {
// Arbitrary properties related to the entity
name: 'Setting up tracking easily',
interactive: false,
context: {
// Provides additional information about the state during the event
stage: ['learning', 1] // A logical funnel stage
test: ['engagement', 0] // Key, [value, order]
globals: {
// General properties that apply to every event
language: 'en'
custom: {}, // Additional space for individual setups
user: {
// Contains user identifiers for different identification levels
// Require consent and set manually for sessions building and cross-device
id: 'us3r1d',
device: 'c00k131d',
session: 's3ss10n1d',
// More user-related properties, see below
nested: [
// All nested entities within the main entity
{ type: "github", data: { repo: "walkerOS" } }
consent: { functional: true }, // Status of the granted consent state(s)
id: '1647261462000-01b5e2-5', // Timestamp, group & count of the event
trigger: 'visible', // Name of the trigger that fired
entity: 'promotion', // The entity name involved in the event
action: 'view', // The specific action performed on the entity
timestamp: 1647261462000, // Time when the event fired
timing: 3.14, // Duration how long it took to trigger this event
group: '01b5e2', // Random identifier for all events during a run
count: 2, // Incremental counter of the events in the same run
version: {
// Information about the used implementation setup
client: 'X.X.X', // Semantic version of the used client
tagging: 42, // A version number of the then-used tagging status
source: {
// Details about the origin of the event
type: 'web', // Source type of the event (also app, server, or custom one)
id: '', // Source of the event's origin
previous_id: '' // Previous source (like referrer)

This structure remains consistent across all interactions, whether the event is a page view, page read, product add, or session start and order complete. Event names are a combination of the entities involved (promotion) and the action performed (view).

Data Properties

Data properties describe the entity in more detail. Depending on the entity (e.g. product, order, article) they can vary and provide specific insights relevant to the interaction.


Context refers to the state or environment in which the event was triggered. It could be as simple as a page position or as complex as the logical stage in a user journey, like a shopping journey from inspiration to checkout stage.


Globals describe the overall state influencing events or user behavior. These might include the theme used, page type for web, or cart value.


A reserved space for individual setups to comply with the defined structure, but also to support custom requirements.


There are recommended identifiers used for stitching together user journeys: id, device, and session. This enables cross-device tracking or linking sessions for a cohesive user journey. On a server-side setup, a temporarily hash value is added. Any other user-related information can be added here. A few values are recommended:

interface User extends Properties {
// IDs
id?: string; // User ID
device?: string; // Typically a cookie or local storage ID
session?: string; // Session ID
hash?: string; // Temporary hash for server-side setups
// User related
userAgent?: string; // Full user agent string
browser?: string; // Browser name
browserVersion?: string; // Browser version
deviceType?: string; // Type of device like, mobile, desktop, tablet
language?: string; // User's language settings
country?: string; // Country code
region?: string; // Region code
city?: string; // City name
timezone?: string; // Timezone
os?: string; // Operating system
osVersion?: string; // Operating system version
screenSize?: string; // Screen size
ip?: string; // IP address
internal?: boolean; // Internal user flag

Consent captures the permissions granted by the user, which is crucial for subsequent data processing and helpful to comply with privacy regulations.


The source is the origin of the event, including type (web, app, server), specific site or component, and referrer information for basic journey attribution.


Structured flexibility

The event model is made to fit every company's requirements while maintaining a structured approach for easy access and interpretation.


With walkerOS data is collected directly and built into your code. This ensures control over what, when, and where data is measured, enhancing data management and privacy.

Source of Truth

A single source of truth for data ensures comparability, manageability, and minimizes implementation efforts, preventing data leaks or inaccuracies.


The event model is designed to be resilient and flexible, allowing adaptability to future legal or internal requirements without vendor lock-in.


The model supports diverse use cases beyond e-commerce, including media, (B2B) SaaS, and more, ensuring versatility and comparability.


Mapping involves translating walkerOS events to the formats required by different analytics tools. For example, a product add event in walkerOS can be mapped to add_to_cart in GA4 or a corresponding event in another tool.