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 destination packages and add them to your config:

npm install @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, session: 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 });

---

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';

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.

---

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