Segment
Segment is a customer data platform that routes your
event data to 400+ downstream destinations (analytics, marketing,
warehouses, ...). This destination forwards walkerOS events to Segment via
the official
@segment/analytics-next
(Analytics.js 2.0) SDK, implementing the full Segment Spec surface: track,
identify, group, page, and reset.
Segment is a web destination in the walkerOS flow:
Loads Analytics.js, forwards events as Segment Spec calls, and automatically stamps consent context on every call.
Installation
Setup
- Integrated
- Bundled
Configuration reference
| Property | Type | Description | More |
|---|---|---|---|
apiKey | string | Your Segment source write key. Find it in your Segment workspace under Connections, Sources, Settings, API Keys. Maps to `writeKey` in the Analytics.js `load()` call (like a1B2c3D4e5F6a1B2c3D4e5F6a1B2c3D4). | |
cdnURL | string | Override the CDN URL used for settings fetch. Default: https://cdn.segment.com. Useful for self-hosted Segment proxies. | |
initialPageview | boolean | When true, the SDK fires an automatic initial page() call on load. Default: false — walkerOS sources handle page tracking, so this is disabled to avoid duplicate page views. | |
disableClientPersistence | boolean | When true, prevents any cookie or localStorage writes. Useful for privacy-conscious setups. Default: false. | |
disableAutoISOConversion | boolean | Disable automatic ISO string → Date conversion. Default: false. | |
retryQueue | boolean | Retry failed events. Default: true. | |
obfuscate | boolean | Obfuscate event payloads. Default: false. | |
integrations | Record<string, any> | Enable/disable downstream Segment destinations. Example: { "All": true, "Mixpanel": false }. | |
identify | any | Destination-level identity mapping. Resolves to an object with any of: userId, traits, anonymousId. Fires on the first push and re-fires when the resolved value changes. | |
group | any | Destination-level group mapping. Resolves to an object with: groupId, traits. Fires on the first push and re-fires on change. | |
consent | Record<string, string> | Mapping from walkerOS consent keys → Segment `categoryPreferences` keys. Example: { "marketing": "Advertising", "analytics": "Analytics" }. When omitted, walkerOS keys are forwarded 1:1 to Segment. |
The Settings type extends Segment's InitOptions, so every passthrough
option (cookie, storage, integrations, plan, retryQueue, ...) works alongside
the walkerOS-specific fields above.
Mapping data.examples
The code data.examples are interactive. You can edit the code to generate your individual event mapping.
Default event forwarding
Every walkerOS event becomes analytics.track(name, properties).
Without include config, properties is empty. Add include: ['data']
to the destination config to forward event data as properties.
User login identify
Per-event identity with reserved Segment Spec traits (email, name,
plan, company). skip: true suppresses the default track() call so
only the identity side effect runs.
Group assignment
Attach a user to a company and set the company's traits in a single
group() call.
Page views
Segment's page() is first-class. Configure it explicitly via
mapping.settings.page.
Order Completed (Segment Ecommerce Spec)
A single track('Order Completed', { products: [...] }) call using
mapping.name for the PascalCase event name and mapping.data with a
nested loop to build the products array inline.
Consent
The destination supports two complementary consent mechanisms:
Automatic context forwarding. When settings.consent is configured,
every track, identify, group, and page call is stamped with
context.consent.categoryPreferences. walkerOS consent keys are remapped
to Segment category names:
Deferred-load consent pattern. When config.consent is declared,
AnalyticsBrowser.load() is held until the first walker consent command
that grants all required keys. This is Segment's primary consent mechanism
Analytics.js has no optOut() method, so the only way to enforce consent
is to avoid loading the SDK in the first place.
Scope Notes
alias()andscreen()are intentionally deferred.alias()is a legacy identity-linking method;screen()is mobile-only.- Plugins, source middleware, and destination middleware cannot be
serialized in JSON flow configs. Register them programmatically on the
returned
AnalyticsBrowserinstance if needed.