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:

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

Settings

Property	Type	Description	More
elb	string	Global function name for event tracking
name	string	Global instance name
run	boolean	Auto-initialize walker.js on load
browser	object | boolean	Browser source configuration
dataLayer	object | boolean	DataLayer source configuration
collector	object	Collector configuration including destinations and consent settings

Browser Source Settings

Property	Type	Description	More
browser.run	boolean	Auto-start DOM tracking
browser.session	boolean	Enable session tracking
browser.scope	Element	DOM element scope for tracking
browser.pageview	boolean	Enable automatic page view events

DataLayer Settings

Property	Type	Description	More
dataLayer	boolean	Enable dataLayer integration with defaults
dataLayer.name	string	DataLayer variable name
dataLayer.prefix	string	Event prefix for dataLayer events

Collector Settings

Property	Type	Description	More
collector.consent	object	Default consent state
collector.destinations	object	Destination configurations

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 & 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.

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();

Related Documentation

• 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.