Event model

The walkerOS event model was created to support analytics, marketing, privacy and data science needs.

Entity-Action Approach

The Entity-Action approach is core of the walkerOS event model. It's a framework designed to capture user interactions in a structured yet flexible way. 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 structure of user behavior.

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.

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.

Event Structure

A walkerOS event consists of three components:

• a trigger (e.g. load)
• an entity (e.g. page)
• an action (e.g. view)

Here's an example of the structure and components of a walkerOS event. 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
    source: 'X.X.X', // Semantic version of the used source
    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: 'https://github.com/elbwalker/walkerOS', // Source of the event's origin
    previous_id: 'https://www.elbwalker.com/', // Previous source (like referrer)
  },
};

Event names are a combination of the entities involved (promotion) and the action performed (view).

The structure remains consistent across all interactions, whether the event e.g. is a page view, session start, product visible, or order complete.

Data Properties

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

Context

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

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

Custom

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

User

There are recommended identifiers used for stitching user journeys together: 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 also be added. 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

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

Source

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

Strengths

Structured flexibility

walkerOS is the single source of truth of data collection. The event model ensures comparability, manageability, and minimizes implementation efforts, preventing data leaks or inaccuracies.

Vendor-agnostic

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

Industry-agnostic

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

info

If you need professional support with your walkerOS implementation, check out our services.