walkerOS: Open-Source tagging and event data collection

walkerOS captures, structures, and routes events with built-in support for consent management — all directly in your code. No fragile UI configs. No black-box logic. Just tracking infrastructure you can version, test, and trust.

Why walkerOS?

• Independence: Make your data collection independent from single vendor specifications to reduce complexity and extra code whenever you add or remove a new service. Keep maintenance effort to a minimum.
• Scalability: DOM-based, component-level frontend tagging makes tracking user behavior declarative, reusable, and easy to maintain.
• Privacy-first approach: Built-in consent handling and privacy controls help you meet compliance from day one.
• Type-safe tracking: Built with TypeScript to catch tracking errors at compile time, not in production. Get IDE autocomplete for APIs and destination configs, prevent data structure mistakes.

How it works

Quick Start

npm

Install the required packages from npm:

npm install @walkeros/collector @walkeros/web-source-browser

Initialize walkerOS in your project:

import { createCollector } from '@walkeros/collector';
import { createSource } from '@walkeros/core';
import { sourceBrowser } from '@walkeros/web-source-browser';

// Initialize walkerOS
export async function initializeWalker() {
  const { collector } = await createCollector({
    sources: {
      browser: createSource(sourceBrowser, {
        settings: {
          pageview: true,
          session: true,
          elb: 'elb', // Browser source will set window.elb automatically
        },
      }),
    },
    destinations: {
      console: {
        push: (event) => console.log('Event:', event),
      },
    },
  });
}

script tag

For websites without build tools, you can install from a CDN:

<script>
  // Load the collector, core utilities, and source
  const { createCollector } = await import(
    'https://cdn.jsdelivr.net/npm/@walkeros/collector/dist/index.mjs'
  );
  const { createSource } = await import(
    'https://cdn.jsdelivr.net/npm/@walkeros/core/dist/index.mjs'
  );
  const { sourceBrowser } = await import(
    'https://cdn.jsdelivr.net/npm/@walkeros/web-source-browser/dist/index.mjs'
  );

  // Initialize walkerOS
  const { collector, elb } = await createCollector({
    destinations: {
      console: {
        push: (event) => console.log('Event:', event),
      },
    },
    sources: {
      browser: createSource(sourceBrowser, {
        settings: {
          prefix: 'data-elb',
          pageview: true,
          session: true,
        },
      }),
    },
  });
</script>

Example: React

Here's a quick look at how to integrate walkerOS into a React application.

1. Create a walker setup file:

// src/walker.ts
import type { Collector, WalkerOS } from '@walkeros/core';
import { createCollector } from '@walkeros/collector';
import { createSource } from '@walkeros/core';
import { createTagger, sourceBrowser } from '@walkeros/web-source-browser';

declare global {
  interface Window {
    elb: WalkerOS.Elb;
    walker: Collector.Instance;
  }
}

export async function initializeWalker(): Promise<void> {
  if (window.walker) return;

  const { collector } = await createCollector({
    run: false, // Defer run to handle route changes
    sources: {
      browser: createSource(sourceBrowser, {
        settings: { pageview: true, session: true, elb: 'elb' },
      }),
    },
    destinations: {
      console: { push: (event) => console.log('Event:', event) },
    },
  });

  window.walker = collector;
}

const taggerInstance = createTagger();
export function tagger(entity?: string) {
  return taggerInstance(entity);
}

2. Integrate into your App component:

// src/App.tsx
import { useLocation } from 'react-router-dom';
import { useEffect, useRef } from 'react';
import { initializeWalker } from './walker';

function App() {
  const location = useLocation();
  const hasInitialized = useRef(false);
  const firstRun = useRef(true);

  useEffect(() => {
    // Prevent React StrictMode double execution
    if (!hasInitialized.current) {
      initializeWalker();
      hasInitialized.current = true;
    }
  }, []);

  useEffect(() => {
    // Use walker run to trigger page views on route changes
    if (firstRun.current) {
      firstRun.current = false;
      return;
    }
    window.elb('walker run');
  }, [location]);

  // ... your app routes
}

3. Tag your components:

// src/components/ProductDetail.tsx
import { tagger } from '../walker';

function ProductDetail({ product }) {
  return (
    <div {...tagger('product').data('id', product.id).get()}>
      <h1>{product.name}</h1>
      <button {...tagger().action('click', 'add').get()}>Add to Cart</button>
    </div>
  );
}

Destinations

Destinations are the endpoints where walkerOS sends your processed events. They transform standardized walkerOS events into the specific formats required by analytics platforms, marketing tools, and data warehouses.

Web Destinations

• API - Send events to your own endpoints
• Google (gtag) - GA4, Google Ads, and GTM integration
• Meta Pixel - Facebook and Instagram advertising
• Plausible Analytics - Privacy-focused web analytics
• Piwik PRO - Privacy-focused analytics platform

Server Destinations

• AWS Firehose - Amazon cloud services integration
• GCP BigQuery - GCP services and BigQuery
• Meta Conversions API - Server-side Facebook/Instagram tracking

Contributing

⭐️ Help us grow and star us. See our Contributing Guidelines to get involved.

Support

Need help? Start a discussion, or reach out via email.

For more insights, visit the talks repository.

License

Licensed under the MIT License.