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. Automatically stamps consent context
on every call.
Segment is a web destination in the walkerOS flow:
Installation
- Integrated
- Bundled
Configuration
This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.
Settings
| 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. |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
identify | any | Per-event identity mapping. Resolves to an object with any of: userId, traits, anonymousId. Use with rule-level `skip: true` on login/identify events. | |
group | any | Per-event group assignment. Resolves to { groupId, traits }. Use with rule-level `skip: true` on company/team events. | |
page | any | Per-event page call configuration. Resolves to { category?, name?, properties? } for analytics.page(), or `true` for an empty analytics.page() that relies on SDK auto-collection. Use with rule-level `skip: true` on page view events. | |
reset | any | Logout trigger. Resolves to a truthy value → analytics.reset() (clears userId, anonymousId, traits). Typically used with skip: true on a user logout rule. |
Examples
Group company
A company update fires Segment analytics.group with a groupId and traits for account-level tracking.
Consent context
Walker consent is stamped on every Segment call via context.consent.categoryPreferences for downstream filtering.
Consent deferred load
A walker consent grant triggers the deferred Segment analytics.load with the configured writeKey.
Default track
A walker event becomes a Segment analytics.track call with the event name and empty properties.
Destination identify
Destination-level identify calls analytics.identify with the resolved userId before firing the default track.
Include data
Destination-level include flattens the event data section into prefixed Segment track properties.
Initialization
Destination bootstrap calls analytics.load with the Segment writeKey and walker default options.
Order completed
A completed order is mapped to the Segment Spec Order Completed event with a nested products array.
Page view
A page view fires Segment analytics.page with category, name, and properties instead of a generic track.
Page view minimal
A mapping with page: true fires an empty analytics.page call relying on Segments auto-collection.
Profile update
A profile update calls Segment analytics.identify with traits and no userId to merge traits into the current profile.
Rule include overrides
A per-rule include replaces the destination-level include so this event forwards only globals.
User login identify
A user login fires Segment analytics.identify with userId and reserved traits such as email, name, and plan.
User logout reset
A user logout calls analytics.reset to clear userId, anonymousId, and traits then generate a new anonymous id.
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.