Optimizely
Optimizely Feature Experimentation
runs A/B tests and feature rollouts. This destination forwards walkerOS events
to Optimizely as conversion events via the official
@optimizely/optimizely-sdk
v6 modular API, calling userContext.trackEvent(eventKey, eventTags) with
optional revenue/value tags and user attributes.
Optimizely is a web destination in the walkerOS flow:
Installation
npm install @walkeros/collector @walkeros/web-destination-optimizely- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import destinationOptimizely from '@walkeros/web-destination-optimizely';
await startFlow({
destinations: {
optimizely: {
code: destinationOptimizely,
config: {
settings: {
sdkKey: 'YOUR_SDK_KEY',
userId: 'user.id',
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "web"
},
"destinations": {
"optimizely": {
"package": "@walkeros/web-destination-optimizely",
"config": {
"settings": {
"sdkKey": "YOUR_SDK_KEY",
"userId": "user.id"
}
}
}
}
}
}
}The quickstart above sets no consent, so the Optimizely client starts and
receives every event without analytics consent, and a revocation changes
nothing. Add consent: { analytics: true } to config, next to settings,
before you go live (see gate a destination).
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 |
|---|---|---|---|
sdkKey | string | Your Optimizely Feature Experimentation SDK key. Find it in your Optimizely project under Settings > Environments. | |
userId | any | walkerOS mapping value to resolve userId for experiment bucketing. Example: "user.id", or the fallback chain ["user.id", "user.device"]. An event where it resolves to no string fails with missing-input. | |
attributes | any | User attributes for audience targeting. Resolves to Record<string, unknown>. Applied through createUserContext() when the user context is created: on the first event and on every event whose userId differs from the previous event's. A change while the userId stays the same is not applied. | |
updateInterval | integer | Polling interval for datafile updates in milliseconds. Default: 60000. | |
autoUpdate | boolean | Auto-update datafile via polling. Default: true. | |
batchSize | integer | Batch event processor: number of events per batch. Default: 10. | |
flushInterval | integer | Batch event processor: flush interval in milliseconds. Default: 1000. |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
eventKey | string | Has no effect: the event key sent to Optimizely is the rule's name, or the walkerOS event name. Set the rule's name to an event created in your Optimizely project. | |
revenue | any | Revenue mapping. Resolves to an integer in cents (e.g. 7281 = $72.81). Passed as eventTags.revenue to trackEvent(). | |
value | any | Numeric value mapping. Resolves to a float. Passed as eventTags.value to trackEvent(). | |
eventTags | any | Additional event tags. Resolves to Record<string, unknown>. Spread into the eventTags object passed to trackEvent(). | |
attributes | any | Per-event user attributes override. Resolves to Record<string, unknown>. Applied via setAttribute() before this event's trackEvent() call. |
Examples
Attributes only
A profile update sets Optimizely user attributes without firing a trackEvent for user enrichment.
{
"name": "profile update",
"data": {
"plan": "premium",
"country": "DE"
},
"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": "cdab217f05413147",
"trigger": "test",
"entity": "profile",
"action": "update",
"timestamp": 1700000105000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"silent": true,
"settings": {
"attributes": {
"map": {
"plan": "data.plan",
"country": "data.country"
}
}
}
}optimizely.setAttribute("plan", "premium");
optimizely.setAttribute("country", "DE")Consent revoked
For a destination with config.consent { analytics: true }, a walker consent command with analytics denied makes no Optimizely call: walkerOS stops tracking for the destination, and the client stays ready for the next grant.
{
"analytics": false
}// no outputDefault event
A walker event becomes an Optimizely trackEvent call with the event name and empty eventTags.
{
"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": "f0cc5f6fec3d8eeb",
"trigger": "load",
"entity": "page",
"action": "view",
"timestamp": 1700000100000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}optimizely.trackEvent("page view", {})Mapped event key
A mapping renames the walker event to an Optimizely event key defined in the project.
{
"name": "product view",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420,
"currency": "EUR"
},
"context": {
"shopping": [
"detail",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [],
"consent": {
"functional": true
},
"id": "db22fb16c70f663d",
"trigger": "load",
"entity": "product",
"action": "view",
"timestamp": 1700000101000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "product_viewed"
}optimizely.trackEvent("product_viewed", {})Purchase revenue
An order fires an Optimizely purchase event with revenue in cents, value, and additional event tags.
{
"name": "order complete",
"data": {
"revenue_cents": 55500,
"value": 555,
"currency": "EUR",
"item_count": 3
},
"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": "235d0d7bd7a213f2",
"trigger": "load",
"entity": "order",
"action": "complete",
"timestamp": 1700000102000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "purchase",
"settings": {
"revenue": "data.revenue_cents",
"value": "data.value",
"eventTags": {
"map": {
"currency": "data.currency",
"item_count": "data.item_count"
}
}
}
}optimizely.trackEvent("purchase", {
"revenue": 55500,
"value": 555,
"currency": "EUR",
"item_count": 3
})Signup with attributes
A user signup sets per-event Optimizely attributes via setAttribute before firing the trackEvent.
{
"name": "user signup",
"data": {
"method": "google",
"source": "referral"
},
"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": "24a9495b7812a1bc",
"trigger": "test",
"entity": "user",
"action": "signup",
"timestamp": 1700000103000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "signup",
"settings": {
"attributes": {
"map": {
"signup_method": "data.method",
"referral_source": "data.source"
}
}
}
}optimizely.setAttribute("signup_method", "google");
optimizely.setAttribute("referral_source", "referral");
optimizely.trackEvent("signup", {})When it fails
- missing user on order complete: Without a user id, settings.userId resolves to nothing: no user context can be created, so the push fails with missing-input instead of counting as delivered. Reported as
failedwith codemissing-input. - missing user on page view: Without a user id, settings.userId resolves to nothing: no user context can be created, so the push fails with missing-input instead of counting as delivered. Reported as
failedwith codemissing-input. - missing user on product view: Without a user id, settings.userId resolves to nothing: no user context can be created, so the push fails with missing-input instead of counting as delivered. Reported as
failedwith codemissing-input. - missing user on profile update: Without a user id, settings.userId resolves to nothing: no user context can be created, so the push fails with missing-input instead of counting as delivered. Reported as
failedwith codemissing-input. - missing user on user signup: Without a user id, settings.userId resolves to nothing: no user context can be created, so the push fails with missing-input instead of counting as delivered. Reported as
failedwith codemissing-input.
User ID
Every event needs a user ID, so settings.userId is required: without it the
destination does not start and fails with a config error. An event where
settings.userId resolves to nothing fails with missing-input (the push result lists the destination under
failed and the collector writes an ERROR line). With userId: 'user.id',
that is every event of an anonymous visitor. To send those events too, give a
fallback chain such as userId: ['user.id', 'user.device']; the
session source sets user.device in storage mode.
Event key
The event key sent to Optimizely is the walkerOS event name, or the rule's
name (see the Mapped event key example). The rule setting eventKey has
no effect: use name.
Revenue
Optimizely expects revenue as an integer in cents (e.g. 7281 =
$72.81). The destination passes the resolved value through without
conversion. The caller must provide cents. A revenue or value that does not
resolve to a number, such as the string "7281", is left out.
Consent
With config.consent, the collector holds the destination's events in a queue
until a required consent key is granted, see
consent management. The destination's Optimizely client
sends only the events walkerOS tracks, so a revocation needs no vendor call: the
client keeps running, and new events wait for the next grant.
destinations: {
optimizely: {
code: destinationOptimizely,
config: {
consent: { analytics: true },
settings: {
sdkKey: 'YOUR_SDK_KEY',
userId: 'user.id',
},
},
},
}Feature flags / decide()
This destination does not expose decide(), by design. Experiment decisions
belong in application code, where the UI branches; this package covers
outbound conversion tracking.