Segment

Web Source code Package

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.

Where this fits

Segment is a web destination in the walkerOS flow:

Installation

npm install @walkeros/web-destination-segment

Integrated
Bundled

import { startFlow } from '@walkeros/collector';
import { destinationSegment } from '@walkeros/web-destination-segment';

await startFlow({
destinations: {
  segment: {
    code: destinationSegment,
    config: {
      settings: {
        apiKey: 'YOUR_SEGMENT_WRITE_KEY',
      },
    },
  },
},
});

Add to your flow.json destinations:

"destinations": {
"segment": {
  "package": "@walkeros/web-destination-segment",
  "config": {
    "settings": {
      "apiKey": "YOUR_SEGMENT_WRITE_KEY"
    }
  }
}
}

See bundled mode setup | CLI reference

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
`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.

* Required fields

Mapping

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

Property	Type	Description
`identify`	`any`	Per-event identity mapping. Resolves to an object with any of: userId, traits, anonymousId. Use with rule-level `silent: true` on login/identify events.
`group`	`any`	Per-event group assignment. Resolves to { groupId, traits }. Use with rule-level `silent: 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 `silent: true` on page view events.
`reset`	`any`	Logout trigger. Resolves to a truthy value → analytics.reset() (clears userId, anonymousId, traits). Typically used with silent: 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.

Event

{
  "name": "company update",
  "data": {
    "company_id": "comp-456",
    "company_name": "Acme",
    "industry": "tech",
    "employees": 50,
    "plan": "enterprise"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "f8558f158014aae9",
  "trigger": "test",
  "entity": "company",
  "action": "update",
  "timestamp": 1700000108,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "silent": true,
  "settings": {
    "group": {
      "map": {
        "groupId": "data.company_id",
        "traits": {
          "map": {
            "name": "data.company_name",
            "industry": "data.industry",
            "employees": "data.employees",
            "plan": "data.plan"
          }
        }
      }
    }
  }
}

Out

analytics.group("comp-456", {
  "name": "Acme",
  "industry": "tech",
  "employees": 50,
  "plan": "enterprise"
})

Consent context

Walker consent is stamped on every Segment call via context.consent.categoryPreferences for downstream filtering.

Event

{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "analytics": true,
    "marketing": true
  },
  "id": "0e56a4e8127c3f8b",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000112,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Out

analytics.track("product view", {}, {
  "context": {
    "consent": {
      "categoryPreferences": {
        "Analytics": true,
        "Advertising": true
      }
    }
  }
})

Consent deferred load

A walker consent grant triggers the deferred Segment analytics.load with the configured writeKey.

Event

{
  "analytics": true
}

Out

analytics.load({
  "writeKey": "test-project"
}, {
  "initialPageview": false
})

Default track

A walker event becomes a Segment analytics.track call with the event name and empty properties.

Event

{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "9fbabca89f44ee3e",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000100,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Out

analytics.track("product view", {})

Destination identify

Destination-level identify calls analytics.identify with the resolved userId before firing the default track.

Event

{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "d09754eaa15c1305",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000104,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Out

analytics.identify("us3r", {});

analytics.track("page view", {})

Include data

Destination-level include flattens the event data section into prefixed Segment track properties.

Event

{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "201fb7c8cee3e64a",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000102,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Out

analytics.track("product view", {
  "data_id": "ers",
  "data_name": "Everyday Ruck Snack",
  "data_color": "black",
  "data_size": "l",
  "data_price": 420
})

Initialization

Destination bootstrap calls analytics.load with the Segment writeKey and walker default options.

Event

{
  "settings": {
    "apiKey": "test-project"
  }
}

Out

analytics.load({
  "writeKey": "test-project"
}, {
  "initialPageview": false
})

Order completed

A completed order is mapped to the Segment Spec Order Completed event with a nested products array.

Event

{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 555
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "5219a61f8fd495d0",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000111,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "name": "Order Completed",
  "data": {
    "map": {
      "order_id": "data.id",
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "shipping": "data.shipping",
      "tax": "data.taxes",
      "total": "data.total",
      "products": {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "e=>{var t;return\"number\"==typeof(null==(t=null==e?void 0:e.data)?void 0:t.price)}"
            },
            "map": {
              "product_id": "data.id",
              "name": "data.name",
              "price": "data.price",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              },
              "currency": {
                "key": "data.currency",
                "value": "EUR"
              }
            }
          }
        ]
      }
    }
  }
}

Out

analytics.track("Order Completed", {
  "order_id": "0rd3r1d",
  "currency": "EUR",
  "shipping": 5.22,
  "tax": 73.76,
  "total": 555,
  "products": [
    {
      "product_id": "ers",
      "name": "Everyday Ruck Snack",
      "price": 420,
      "quantity": 1,
      "currency": "EUR"
    },
    {
      "product_id": "cc",
      "name": "Cool Cap",
      "price": 42,
      "quantity": 1,
      "currency": "EUR"
    }
  ]
})

Page view

A page view fires Segment analytics.page with category, name, and properties instead of a generic track.

Event

{
  "name": "page view",
  "data": {
    "category": "docs",
    "title": "Getting Started",
    "section": "tutorials"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "b00838fe28e78730",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000109,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "silent": true,
  "settings": {
    "page": {
      "map": {
        "category": "data.category",
        "name": "data.title",
        "properties": {
          "map": {
            "section": "data.section"
          }
        }
      }
    }
  }
}

Out

analytics.page("docs", "Getting Started", {
  "section": "tutorials"
})

Page view minimal

A mapping with page: true fires an empty analytics.page call relying on Segments auto-collection.

Event

{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "cee6462dfbc459df",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000110,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "silent": true,
  "settings": {
    "page": true
  }
}

Out

analytics.page()

Profile update

A profile update calls Segment analytics.identify with traits and no userId to merge traits into the current profile.

Event

{
  "name": "profile update",
  "data": {
    "name": "Jane Q. Doe",
    "avatar_url": "https://example.com/avatar.png",
    "phone": "+1234567890"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "400a7e2ace92bd14",
  "trigger": "test",
  "entity": "profile",
  "action": "update",
  "timestamp": 1700000106,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "silent": true,
  "settings": {
    "identify": {
      "map": {
        "traits": {
          "map": {
            "name": "data.name",
            "avatar": "data.avatar_url",
            "phone": "data.phone"
          }
        }
      }
    }
  }
}

Out

analytics.identify(null, {
  "name": "Jane Q. Doe",
  "avatar": "https://example.com/avatar.png",
  "phone": "+1234567890"
})

Rule include overrides

A per-rule include replaces the destination-level include so this event forwards only globals.

Event

{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 555
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "4ea609713a6bda83",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000103,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "include": [
    "globals"
  ]
}

Out

analytics.track("order complete", {
  "globals_pagegroup": "shop"
})

User login identify

A user login fires Segment analytics.identify with userId and reserved traits such as email, name, and plan.

Event

{
  "name": "user login",
  "data": {
    "user_id": "new-user-123",
    "email": "user@acme.com",
    "name": "Jane Doe",
    "plan": "premium",
    "company_name": "Acme",
    "company_id": "comp-456"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "30b46037ed0bfed6",
  "trigger": "test",
  "entity": "user",
  "action": "login",
  "timestamp": 1700000105,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "silent": true,
  "settings": {
    "identify": {
      "map": {
        "userId": "data.user_id",
        "traits": {
          "map": {
            "email": "data.email",
            "name": "data.name",
            "plan": "data.plan",
            "company": {
              "map": {
                "name": "data.company_name",
                "id": "data.company_id"
              }
            }
          }
        }
      }
    }
  }
}

Out

analytics.identify("new-user-123", {
  "email": "user@acme.com",
  "name": "Jane Doe",
  "plan": "premium",
  "company": {
    "name": "Acme",
    "id": "comp-456"
  }
})

User logout reset

A user logout calls analytics.reset to clear userId, anonymousId, and traits then generate a new anonymous id.

Event

{
  "name": "user logout",
  "data": {
    "string": "foo",
    "number": 1,
    "boolean": true,
    "array": [
      0,
      "text",
      false
    ]
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "333ebd80707d2b61",
  "trigger": "test",
  "entity": "user",
  "action": "logout",
  "timestamp": 1700000107,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}

Mapping

{
  "silent": true,
  "settings": {
    "reset": true
  }
}

Out

analytics.reset()

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:

settings: {
apiKey: 'WRITE_KEY',
consent: {
  analytics: 'Analytics',
  marketing: 'Advertising',
},
}

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.

destinations: {
segment: {
  code: destinationSegment,
  config: {
    consent: { analytics: true },
    settings: { apiKey: 'WRITE_KEY' },
  },
},
}

Scope notes

alias() and screen() 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 AnalyticsBrowser instance if needed.

💡 Need implementation support?

elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)

Installation​

Configuration​

Settings​

Mapping​

Examples

Group company

Consent context

Consent deferred load

Default track

Destination identify

Include data

Initialization

Order completed

Page view

Page view minimal

Profile update

Rule include overrides

User login identify

User logout reset

Consent​

Scope notes​

Installation

Configuration

Settings

Mapping

Consent

Scope notes