React Quickstart

This guide shows you how to integrate walkerOS into your React application with automatic pageview tracking and component-level event tracking.

Key concepts

• Single file setup: One initialization file, direct usage in App.tsx
• No providers needed: Direct integration in your main App component
• StrictMode safe: Handles React's double execution correctly
• Data attributes: Use the tagger helper for clean component tracking

Installation

First, install the required walkerOS packages:

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

Setup

1. walker initialization

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

// Global type declarations
declare global {
  interface Window {
    elb: WalkerOS.Elb;
    walker: Collector.Instance;
  }
}

let walkerReady: Promise<void> | undefined;

// Starts the flow once, later calls return the same promise
export function initializeWalker(): Promise<void> {
  walkerReady ??= startWalker();
  return walkerReady;
}

async function startWalker(): Promise<void> {
  const { collector } = await startFlow({
    consent: { functional: true },
    sources: {
      browser: {
        code: sourceBrowser,
        config: {
          settings: {
            pageview: true,
            history: true, // a page view on every route change
            elb: 'elb',
          },
        },
      },
    },
    destinations: {
      console: {
        code: {
          type: 'console',
          config: {},
          push: (event) => console.log('Event:', event.name),
        },
      },
    },
  });

  // Set global window object
  window.walker = collector;
}

// Tagger helper for easy component tagging
const taggerInstance = createTagger();

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

2. App integration

Integrate directly in your main App component. The collector sends the first page view when it starts. With history: true the browser source sends one on every route change and picks up the tagged elements the new route renders, so the App only starts the walker once. Some routers set the new page title after the route change, so its page view can carry the previous title. For exact titles, see single-page apps.

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

function App() {
  useEffect(() => {
    // Starts once, also when React StrictMode runs effects twice
    initializeWalker();
  }, []);

  return (
    <div className="min-h-screen bg-gray-50">
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/category" element={<Category />} />
        <Route path="/product/:id" element={<Detail />} />
      </Routes>
    </div>
  );
}

export default App;

Component tagging

Use the tagger helper for clean component tracking:

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

function ProductDetail({ productId }: { productId: string }) {
  const product = getProductById(parseInt(productId));
  if (!product) return null;

  return (
    <div
      {...tagger()
        .entity('product')
        .action('load', 'view')
        .data('productId', productId)
        .get()}
      className="bg-white rounded-lg shadow p-8"
    >
      <h1
        {...tagger('product').data('name', product.name).get()}
        className="text-3xl font-bold mb-2"
      >
        {product.name}
      </h1>

      <p
        {...tagger('product').data('price', product.price).get()}
        className="text-3xl font-bold text-blue-600"
      >
        €{product.price}
      </p>

      <button
        {...tagger().action('click', 'add').get()}
        className="w-full bg-blue-600 text-white py-3 px-6 rounded-lg"
      >
        Add to Cart
      </button>
    </div>
  );
}

// Without tagger helper (verbose)
<div
  data-elb="product"
  data-elbaction="load:view"
  data-elb-product={`id:${product.id};name:${product.name};price:${product.price}`}
>

// With tagger helper (clean)
<div
  {...tagger()
    .entity('product')
    .action('load', 'view')
    .data('id', product.id)
    .data('name', product.name)
    .data('price', product.price)
    .get()}
>

info

When using the tagger helper, make sure to call .get() at the end of the chain.

Manual event tracking

Use the elb function for custom events:

import type { FormEvent } from 'react';

function CheckoutForm({ total, itemCount }: { total: number; itemCount: number }) {
  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    window.elb({
      name: 'checkout complete',
      data: { total, items: itemCount },
    });
  };

  return <form onSubmit={handleSubmit}>{/* Form fields */}</form>;
}

Testing

In step 1, we added a console destination. It logs each event's name to the console. Open your browser's developer console and navigate from the home page to a product page to see tracked events. The first page view is the home page, the second the product page, then the product's view:

Event: page view
Event: page view
Event: product view

Best practices

1. Use tagger: Clean component tagging with the tagger helper
2. Minimal React code: Keep React integration as simple as possible
3. Trust walkerOS: No need for custom error handling or state management
4. Direct integration: No providers needed, integrate directly in App component
5. Test with console: Use console destination during development

Troubleshooting

Events not firing

1. Check that window.walker is set in the browser console
2. Verify data attributes are correctly formatted (use data-elb prefix)
3. Ensure walker initialization completed (window.walker.allowed must be true)
4. Check browser console for any error messages

Route changes not tracked

1. Check that the browser source has history: true
2. Remove route-change walker run calls: with history on they send a second page view
3. A route that reuses its component when only a parameter changes does not fire its tagged elements again: remount it per route, for example with key={id}

Next steps

• Configure destinations for your analytics tools
• Set up consent management
• Send it to GA4: the same event arriving live in GA4 DebugView
• Operating modes: choose how to package and deploy