Integrated mode

In Integrated mode, walkerOS lives inside your application code. You configure it with TypeScript, and it deploys as part of your app bundle.

Quickstart

1. Install the collector

npm install @walkeros/collector

2. Send your first event

import { startFlow } from '@walkeros/collector';

const { elb } = await startFlow({
  destinations: {
    console: {
      code: {
        type: 'console',
        config: {},
        push: (event) => console.log('Event:', event.name),
      },
    },
  },
});

await elb('page view', { title: 'Home' });
// -> logs: Event: page view

That's it. You just sent your first event and saw it in the console.

---

Adding destinations

Install the browser source and the destination packages, then add them to your config:

npm install @walkeros/web-source-browser @walkeros/web-destination-api @walkeros/web-destination-gtag

import { startFlow } from '@walkeros/collector';
import { sourceBrowser } from '@walkeros/web-source-browser';
import { destinationAPI } from '@walkeros/web-destination-api';
import { destinationGtag } from '@walkeros/web-destination-gtag';

const { elb } = await startFlow({
  sources: {
    browser: {
      code: sourceBrowser,
      config: {
        settings: { pageview: true },
      },
    },
  },
  destinations: {
    // Send to your API
    api: {
      code: destinationAPI,
      config: {
        settings: { url: 'https://your-api.com/events' },
      },
    },
    // Send to Google Analytics 4
    ga4: {
      code: destinationGtag,
      config: {
        settings: {
          ga4: { measurementId: 'G-XXXXXXXXXX' },
        },
      },
    },
  },
});

---

Adding consent

Add consent requirements to control which destinations receive events:

const { elb } = await startFlow({
  sources: {
    browser: {
      code: sourceBrowser,
      config: { settings: { pageview: true } },
    },
  },
  destinations: {
    api: {
      code: destinationAPI,
      config: {
        settings: { url: 'https://your-api.com/events' },
        consent: { functional: true }, // Requires functional consent
      },
    },
    ga4: {
      code: destinationGtag,
      config: {
        settings: { ga4: { measurementId: 'G-XXXXXXXXXX' } },
        consent: { analytics: true }, // Requires analytics consent
      },
    },
  },
});

// When user accepts consent
elb('walker consent', { functional: true, analytics: true });

Until a destination's required consent is granted, its events wait in an in-memory queue and are delivered once walker consent grants it. The queue holds up to 1000 events per destination by default; when it is full, the oldest events are dropped. Change the limit with config.queueMax on the destination, see buffer bounds.

---

Key concepts

The code: Property

In Integrated mode, you pass actual code references:

sources: {
  browser: {
    code: sourceBrowser,  // Direct import, not a string
  },
},

This differs from Bundled mode where you use package: with a string reference.

The elb Function

startFlow() returns an elb function for tracking events:

const { elb } = await startFlow({ ... });

// Track events with entity-action format
elb('page view', { title: 'Home' });
elb('product add', { id: 'abc', name: 'Widget', price: 29.99 });
elb('order complete', { total: 99.99, currency: 'USD' });

Type safety

Integrated mode gives you full TypeScript support:

import type { WalkerOS } from '@walkeros/core';

const { elb } = await startFlow<WalkerOS.Elb>({
  // Full autocomplete and type checking
});

---

Framework examples

React

// hooks/useWalker.ts
import { useEffect, useState } from 'react';
import { startFlow } from '@walkeros/collector';
import { sourceBrowser } from '@walkeros/web-source-browser';
import type { WalkerOS } from '@walkeros/core';

export function useWalker() {
  const [elb, setElb] = useState<WalkerOS.Elb | null>(null);

  useEffect(() => {
    startFlow({
      sources: {
        browser: { code: sourceBrowser, config: { settings: { pageview: true } } },
      },
    }).then(({ elb }) => setElb(() => elb));
  }, []);

  return elb;
}

Next.js

// app/providers.tsx
'use client';
import { useEffect } from 'react';
import { startFlow } from '@walkeros/collector';
import { sourceBrowser } from '@walkeros/web-source-browser';

export function WalkerProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    startFlow({
      sources: {
        browser: { code: sourceBrowser, config: { settings: { pageview: true } } },
      },
    });
  }, []);

  return <>{children}</>;
}

---

See your event

The basic setup above logs every event it receives. Run it (Node, or your app's dev server) and push an event:

await elb('page view', { title: 'Home' });
// -> logs: Event: page view

Integrated mode verifies where it runs: in your console. For an offline CLI test loop with mocked destinations, use bundled mode.

---

Observe a running flow

The console loop above is local. To watch a running flow's events live, add the public connect pair to startFlow once:

const { elb } = await startFlow({
  // Both values are public and safe to commit
  observe: { url: 'https://observer.example.com', binding: 'pb_x' },
  // ...your sources and destinations
});

Nothing is sent yet: the per-session credential arrives out-of-band as a ?elbObserve= URL parameter, so committed code never contains a secret. On the server, read the connect config from the environment instead:

import { observeFromEnv } from '@walkeros/core';

const { elb } = await startFlow({
  observe: observeFromEnv(process.env),
  // ...your sources and destinations
});

See Observe for the full setup, the environment variables, and the credential lifecycle.

---

Next steps

• Event Model: How events are structured
• Mapping: Transform events for destinations
• Browser Source: DOM-based automatic tracking
• Destinations: Available destination packages

---

See also

• Bundled mode: Configure with JSON, build with CLI
• Collector reference: Full startFlow() API documentation