Skip to main content
Ask your AI

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({ name: 'page view', data: { title: 'Home' } });
// -> logs: Event: page view

This sends your first event and logs it to 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: {
        loadScript: true,
        settings: {
          ga4: { measurementId: 'G-XXXXXXXXXX', pageview: false },
        },
      },
    },
  },
});

loadScript: true adds gtag.js to the page; without it, events reach GA4 only if your page loads gtag.js itself. pageview: false stops gtag from sending a page view of its own, because the browser source already sends one.


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: {
        loadScript: true,
        settings: { ga4: { measurementId: 'G-XXXXXXXXXX', pageview: false } },
        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 elb. Pass it a partial event: name is required, and the collector adds the rest, such as id, timestamp and source.

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

const result = await elb({
name: 'product add',
data: { id: 'abc', name: 'Widget', price: 29.99 },
});

if (!result.ok) console.error(result.failed ?? result.error);

result.done lists the destinations that received the event, result.queued those waiting (for consent, for a batch flush, or while the destination is held), and result.failed those whose push failed, each with a reason. When the event was rejected or a step before the destinations failed, result.error says why. The event model lists the fields a partial event takes and what the collector adds.

Type safety​

Each step is typed by the package you pass as code. Its settings, the settings of its mapping rules and its env keys autocomplete, and a setting the package does not have is a type error:

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

const { elb } = await startFlow({
sources: {
browser: {
code: sourceBrowser,
config: { settings: { pageview: true, prefix: 'data-elb' } },
},
},
destinations: {
gtag: {
code: destinationGtag,
config: {
loadScript: true,
// `measurementID` instead of `measurementId` would be a type error
settings: { ga4: { measurementId: 'G-XXXXXXXXXX', pageview: false } },
mapping: {
order: { complete: { name: 'purchase', settings: { ga4: {} } } },
},
},
},
},
});

Write the config inline in the startFlow call. A config kept in a separate variable still compiles and is checked, but not for unknown keys. To declare a config on its own, annotate it as Collector.InitConfig; its settings then stay unchecked. An explicit type argument such as startFlow<WalkerOS.Elb>(...) turns the checking off for the whole call.


Framework examples​

Start the flow once per page load. React StrictMode runs effects twice in development, so a startFlow call placed directly in useEffect starts two flows, and each sends its own page view. Keep the start in a module-level promise. With history: true the browser source also sends a page view on every route change:

// walker.ts
import { startFlow } from '@walkeros/collector';
import { sourceBrowser } from '@walkeros/web-source-browser';

let walkerReady: ReturnType<typeof startWalker> | undefined;

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

function startWalker() {
return startFlow({
sources: {
browser: {
code: sourceBrowser,
config: { settings: { pageview: true, history: true } },
},
},
});
}

initializeWalker() resolves to { collector, elb }. Call it from an effect:

// App.tsx
import { useEffect } from 'react';
import { initializeWalker } from './walker';

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

return <main>{/* your routes */}</main>;
}

The React and Next.js quickstarts show the complete setup, including the Pages Router and component tagging.


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({ name: 'page view', data: { title: 'Home' } });
// -> logs: Event: page view

In Integrated mode you check events where the flow 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:

import { pageObserveSlot } from '@walkeros/web-core';

const { elb } = await startFlow({
  // url and binding are public and safe to commit
  observe: {
    url: 'https://observer.example.com',
    binding: 'pb_x',
    slot: pageObserveSlot(), // web only: keeps the credential in this browser
  },
  // ...your sources and destinations
});

In a browser slot is required; without it one error line names pageObserveSlot and Observe stays off.

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​


See also​

💡 Not sure which mode fits your stack?
We are happy to talk through your architecture and recommend the right approach. Start with a free scoping call.