/walkeros-understanding-events

name: walkeros-understanding-events
description:
  Use when creating walkerOS events, understanding event structure, or working
  with event properties. Covers entity-action naming, event properties,
  statelessness, and vendor-agnostic design.

Understanding walkerOS Events

Overview

walkerOS events are self-describing, stateless, vendor-agnostic data structures. They capture user interactions in a standardized format that can be transformed for any destination.

**Core principle:** Events describe WHAT happened, not WHERE it goes. Stateless. Self-describing. Industry-agnostic.

Entity-Action Naming (Critical)

**STRICT REQUIREMENT:** All events use "entity action" format with space separation.

// Correct
'page view';
'product add';
'order complete';
'button click';

// Wrong
'page_view'; // underscore
'pageview'; // no separator
'purchase'; // no entity
'add_to_cart'; // wrong format

**Parsing:** `const [entity, action] = event.split(' ')`

• **Entity:** Noun (page, product, user, order, button)
• **Action:** Verb (view, add, complete, click, login)

Event Properties

See [packages/core/src/types/walkeros.ts](../../packages/core/src/types/walkeros.ts) for canonical types (Event interface, plus event helpers in `event.ts`).

| Property | Type | Purpose | Example | | ----------------- | ------ | ----------------------------------------------------------- | -------------------------------------- | | `name` | string | "entity action" format | `"product view"` | | `data` | object | Entity-specific properties | `{ id: "P123", price: 99 }` | | `context` | object | State/environment info (optional) | `{ stage: ["checkout", 1] }` | | `globals` | object | Global properties | `{ language: "en" }` | | `user` | object | User identification | `{ id: "user123" }` | | `nested` | array | Related entities (optional) | `[{ entity: "product", data: {...} }]` | | `consent` | object | Consent states | `{ marketing: true }` | | `id` | string | W3C span_id, 16 lowercase hex chars, generated by collector | `"0123456789abcdef"` | | `timestamp` | number | Auto-generated Unix ms | `1647261462000` | | `entity` | string | Parsed from name | `"product"` | | `action` | string | Parsed from name | `"view"` | | `source.type` | string | Source kind (`browser`, `dataLayer`, `cookiefirst`, ...) | `"browser"` | | `source.platform` | string | Runtime platform (`web`, `server`) | `"web"` | | `source.schema` | string | Source-emitted schema/version (optional) | `"datalayer-v2"` | | `source.trace` | string | Run-scoped W3C trace_id, shared by every event of a run | `"0123...cdef"` (32 hex) | | `source.count` | number | Per-run emission sequence (1, 2, 3, ...) | `1` | | `source.release` | object | Per-flow config release map, accumulates across crossings | `{ web: "3", server: "5" }` |

data Property

Entity-specific properties. Schema-free but consistent within entity type.

// product entity
data: { id: "P123", name: "Laptop", price: 999, currency: "USD" }

// page entity
data: { title: "Home", path: "/", referrer: "https://..." }

context Property

Hierarchical state information. Format: `{ name: [value, order] }`. Optional.

context: {
  stage: ["checkout", 1],    // checkout stage, first step
  test: ["variant-A", 0],    // A/B test variant
  group: ["premium", 2]      // user segment
}

globals Property

Properties that apply to ALL events in the session.

globals: {
  language: "en",
  currency: "USD",
  environment: "production"
}

nested Property

Related entities captured together. Optional.

// Order with line items
nested: [
  { entity: 'product', data: { id: 'P1', quantity: 2 } },
  { entity: 'product', data: { id: 'P2', quantity: 1 } },
];

user Property

User identification across sessions.

user: {
  id: "user123",        // Your user ID
  device: "device456",  // Device fingerprint
  session: "sess789",   // Session ID
  hash: "a1b2c3...",    // Hashed identifier (for example a hashed email)
  optout: false,        // User opted out of tracking (boolean)
  segment: "vip"        // Custom keys are allowed, each holds a property value
}

The declared fields keep their types: `email` must be a valid address, so a hashed email goes to `hash`, never to `email`. Any other key is a custom user attribute with a property value and passes the validate transformer's `format: true` check.

source Property

Where the event came from. The collector enriches the event with `source` data based on which source emitted it.

source: {
  type: 'browser',         // source kind (browser, dataLayer, cookiefirst, ...)
  platform: 'web',         // runtime: 'web' or 'server'
  version: '4.0.0',        // external source-emitter version (collector no longer sets this)
  schema: 'datalayer-v2',  // optional schema/version emitted by the source
  trace: '0123...cdef',    // run-scoped W3C trace_i