walker.js

Walker.js is a pre-built walkerOS application that combines both the browser and dataLayer sources with the collector and a default dataLayer destination into a pre-build package. It's designed for users who want instant web tracking without complex setup or configuration.

Installation

Option 1: npm package

npm install @walkeros/walker.js

Option 2: CDN

<script
async
data-elbconfig="elbConfig"
src="https://cdn.jsdelivr.net/npm/@walkeros/walker.js@latest/dist/walker.js"
></script>

Basic setup

1. Add event queueing (recommended)

Add this script before walker.js loads to queue events during initialization:

<script>
function elb() {
  (window.elbLayer = window.elbLayer || []).push(arguments);
}
</script>

2. Include walker.js

<script async data-elbconfig="elbConfig" src="./walker.js"></script>

3. Configure destinations

<script>
window.elbConfig = {
  collector: {
    destinations: {
      console: {
        push: (event) => console.log('Event:', event),
      },
      api: {
        push: async (event) => {
          await fetch('/api/events', {
            method: 'POST',
            body: JSON.stringify(event),
          });
        },
      },
    },
  },
};
</script>

Configuration options

Walker.js supports multiple configuration approaches with different priorities:

Script tag data-elbconfig (highest priority)
window.elbConfig (default fallback)
Manual initialization (when run: false)

Settings

Property	Type	Description
`collector`	`any`	Collector configuration (Collector.InitConfig)
`browser`	`any`	Browser source configuration (Partial<SourceBrowser.Settings>)
`dataLayer`	`boolean \| any`	DataLayer configuration (boolean \| Partial<SourceDataLayer.Settings>)
`elb`	`string`	Name for the global elb function (default: "elb")
`name`	`string`	Name for the global instance
`run`	`boolean`	Auto-run on initialization (default: true)

Browser source settings

Property	Type	Description
`prefix`	`string`	Prefix for data attributes (default: data-elb)
`scope`	`string`	DOM scope for event tracking (default: document)
`pageview`	`boolean`	Enable automatic pageview tracking
`capture`	`boolean`	Read click/submit triggers in the capture phase so tagged elements are resolved at click time before app handlers run (set false for the previous bubble-phase behavior)
`elb`	`string`	Name for global elb function
`name`	`string`	Custom name for source instance
`elbLayer`	`boolean \| string \| any`	Enable elbLayer for async command queuing (boolean, string, or Elb.Layer)

DataLayer settings

Property	Type	Description
`name`	`string`	DataLayer variable name (default: dataLayer)
`prefix`	`string`	Event prefix for filtering which events to process
`filter`	`function`	Custom filter function: (event: unknown) => boolean \| Promise<boolean>

Collector settings

Property	Type	Description
`run`	`boolean`	Whether to run collector automatically on initialization
`globalsStatic`	`WalkerOS.Properties`	Static global properties that persist across collector runs
`sessionStatic`	`Collector.SessionStatic`	Static session data that persists across collector runs
`logger`	`Logger.Config`	Logger configuration (level, handler)
`queueMax`	`number`	Maximum events retained in collector.queue (late-registration replay). FIFO drop on overflow. Default 1000.
`name`	`string`	Flow name; keys this flow's entry in event.source.release and the observer flowId.
`release`	`string`	Config release id stamped into event.source.release for this flow.
`consent`	`WalkerOS.Consent`	Initial consent state
`user`	`any`	Initial user data
`globals`	`WalkerOS.Properties`	Initial global properties
`sources`	`Source.InitSources`	Source configurations
`destinations`	`Destination.InitDestinations`	Destination configurations
`transformers`	`Transformer.Configs`	Transformer configurations
`stores`	`Store.Configs`	Store configurations
`custom`	`WalkerOS.Properties`	Initial custom implementation-specific properties
`hooks`	`Collector.Hooks`	Pipeline observation hooks

Full configuration object

window.elbConfig = {
// Global settings
elb: 'elb', // Global function name (default: 'elb')
name: 'walkerjs', // Global instance name
run: true, // Auto-initialize (default: true)

// Browser source settings
browser: {
  run: true, // Auto-start DOM tracking
  session: true, // Enable session tracking
  scope: document.body, // Tracking scope
  pageview: true, // Enable automatic page views
},

// DataLayer integration
dataLayer: true, // Enable dataLayer
// or detailed config:
// dataLayer: {
//   name: 'dataLayer', // DataLayer variable name
//   prefix: 'dataLayer', // Event prefix
// },

// Collector configuration
collector: {
  consent: { functional: true }, // Default consent state
  destinations: {
    // Your destinations here
    console: {
      push: (event) => console.log('Event:', event),
    },
  },
},
};

Inline configuration

Configure directly in the script tag using simple key:value pairs:

<script
async
data-elbconfig="elb:track;run:true;instance:myWalker"
src="./walker.js"
></script>

Named configuration object

Use a custom configuration object name:

<script>
window.trackingConfig = {
  elb: 'track',
  collector: {
    destinations: {
      // Your destinations
    },
  },
};
</script>
<script async data-elbconfig="trackingConfig" src="./walker.js"></script>

Usage

Automatic DOM tracking

Walker.js automatically tracks events based on HTML data attributes:

<!-- Product tracking -->
<div data-elb="product" data-elb-product="id:123;name:Blue T-Shirt;price:29.99">
<button data-elbaction="click:add">Add to Cart</button>
</div>

<!-- Global properties -->
<div data-elbglobals="pagetype:product_detail"></div>

<!-- Context information -->
<div data-elbcontext="section:recommendations"></div>

For detailed information on data attributes, see the Browser Source documentation.

Manual event tracking

Use the global elb function for manual tracking:

// Simple event
elb('button click', {
label: 'interesting',
});

DataLayer integration

Walker.js can integrate with existing dataLayer implementations:

// Enable dataLayer integration
window.elbConfig = {
dataLayer: true, // Uses window.dataLayer by default
};

// Existing dataLayer events will be processed
dataLayer.push({
event: 'purchase',
ecommerce: {
transaction_id: '12345',
value: 25.42,
},
});

Advanced features

Async loading and event queueing

Walker.js handles async loading gracefully with automatic event queueing:

<script>
// 1. Define elb function to queue events
function elb() {
  (window.elbLayer = window.elbLayer || []).push(arguments);
}

// 2. Track events immediately (even before walker.js loads)
elb('product view', { id: '123', name: 'Blue T-Shirt' });
</script>

<!-- 3. Walker.js processes queued events when it loads -->
<script async data-elbconfig="elbConfig" src="./walker.js"></script>

Build variants

Walker.js provides multiple build formats for different environments:

walker.js - Standard IIFE bundle for browsers
index.es5.js - GTM-compatible ES2015 build
index.mjs - ES modules for modern bundlers
index.js - CommonJS for Node.js environments

Programmatic usage

Use walker.js programmatically in applications:

import { createWalkerjs } from '@walkeros/walker.js';

const { collector, elb } = await createWalkerjs({
collector: {
destinations: {
console: { push: console.log },
},
},
browser: {
session: true,
pageview: true,
},
});

Destination configuration

Configure multiple destinations for your events:

window.elbConfig = {
collector: {
destinations: {
// Console logging for development
console: {
push: (event) => console.log('Walker.js Event:', event),
},

// Custom API endpoint
api: {
push: async (event) => {
  await fetch('/api/events', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(event),
  });
},
},
},
},
};

For comprehensive destination options, see the Destinations documentation.

Growing beyond walker.js

Walker.js is a convenience bundle that combines Browser Source, DataLayer Source, and Collector into a single file. It's perfect for getting started, but you may outgrow it.

When to stay with walker.js

✅ Simple tracking needs (pageviews, clicks, forms)
✅ Static sites or traditional server-rendered pages
✅ Quick proof-of-concept or MVP
✅ Teams who prefer minimal setup

When to upgrade

Consider moving to full Integrated or Bundled mode when you need:

Need	Solution
Server-side tracking	Bundled mode with Docker
Custom sources (HTTP, AWS, GCP)	Both modes support server sources
Multiple flows per page	Full Collector configuration
TypeScript integration	Integrated mode
CI/CD versioned configs	Bundled mode
Event mapping/transformation	Both modes with mapping config

Migration path

Walker.js configuration maps directly to full modes:

Integrated
Bundled

// walker.js equivalent in Integrated mode
import { startFlow } from '@walkeros/collector';
import { sourceBrowser } from '@walkeros/web-source-browser';

const { elb } = await startFlow({
  sources: {
    browser: {
      code: sourceBrowser,
      config: { settings: { pageview: true, session: true } },
    },
  },
  destinations: {
    // Your destinations here
  },
  run: true,
});

// walker.js equivalent in Bundled mode (flow.json)
{
  "version": 4,
  "flows": {
    "default": {
      "config": { "platform": "web" },
      "sources": {
        "browser": {
          "package": "@walkeros/web-source-browser",
          "config": { "settings": { "pageview": true, "session": true } }
        }
      },
      "destinations": {
        // Your destinations here
      },
      "collector": { "run": true }
    }
  }
}

The mental model is the same (sources, collector, destinations), just with more control.

Troubleshooting

Common issues

Events not firing: Check that walker.js loaded and configuration is valid.

Missing events: Ensure event queueing function is added before walker.js.

Configuration not applied: Verify data-elbconfig points to the correct object name.

API reference

Factory function

createWalkerjs(config?: Config): Promise<Instance>

Creates a new walker.js instance with the provided configuration.

Instance properties

collector - The walkerOS collector instance
elb - Browser push function for event tracking

Utility functions

import { getAllEvents, getEvents, getGlobals } from '@walkeros/walker.js';

// Get all trackable events on the page
const events = getAllEvents();

// Get events for a specific element and trigger
const button = document.querySelector('button');
const clickEvents = getEvents(button, 'click');

// Get global properties from the page
const globals = getGlobals();

Browser Source - Detailed DOM tracking capabilities
Collector - Event processing and routing
Destinations - Available destination options
DataLayer Source - DataLayer integration details

Walker.js combines all these components into a single, easy-to-use package perfect for getting started with walkerOS quickly.

💡 Need implementation support?

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

Installation​

Option 1: npm package​

Option 2: CDN​

Basic setup​

1. Add event queueing (recommended)​

2. Include walker.js​

3. Configure destinations​

Configuration options​

Settings​

Browser source settings​

DataLayer settings​

Collector settings​

Full configuration object​

Inline configuration​

Named configuration object​

Usage​

Automatic DOM tracking​

Manual event tracking​

DataLayer integration​

Advanced features​

Async loading and event queueing​

Build variants​

Programmatic usage​

Destination configuration​

Growing beyond walker.js​

When to stay with walker.js​

When to upgrade​

Migration path​

Troubleshooting​

Common issues​

API reference​

Factory function​

Instance properties​

Utility functions​

Related documentation​