Skip to main content
Ask your AI

Optimizely

Web Source code Package Beta

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.

Where this fits

Optimizely is a web destination in the walkerOS flow:

Installation​

npm install @walkeros/collector @walkeros/web-destination-optimizely
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',
        },
      },
    },
  },
});

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​

PropertyTypeDescriptionMore
sdkKey*stringYour Optimizely Feature Experimentation SDK key. Find it in your Optimizely project under Settings > Environments.
userId*anywalkerOS 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.
attributesanyUser 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.
updateIntervalintegerPolling interval for datafile updates in milliseconds. Default: 60000.
autoUpdatebooleanAuto-update datafile via polling. Default: true.
batchSizeintegerBatch event processor: number of events per batch. Default: 10.
flushIntervalintegerBatch event processor: flush interval in milliseconds. Default: 1000.
* Required fields

Mapping​

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

PropertyTypeDescriptionMore
eventKeystringHas 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.
revenueanyRevenue mapping. Resolves to an integer in cents (e.g. 7281 = $72.81). Passed as eventTags.revenue to trackEvent().
valueanyNumeric value mapping. Resolves to a float. Passed as eventTags.value to trackEvent().
eventTagsanyAdditional event tags. Resolves to Record<string, unknown>. Spread into the eventTags object passed to trackEvent().
attributesanyPer-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.

Event
{
  "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"
  }
}
Mapping
{
  "silent": true,
  "settings": {
    "attributes": {
      "map": {
        "plan": "data.plan",
        "country": "data.country"
      }
    }
  }
}
Out
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.

Event
{
  "analytics": false
}
Out
// no output

Default event

A walker event becomes an Optimizely trackEvent call with the event name and empty eventTags.

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": "f0cc5f6fec3d8eeb",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000100000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Out
optimizely.trackEvent("page view", {})

Mapped event key

A mapping renames the walker event to an Optimizely event key defined in the project.

Event
{
  "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"
  }
}
Mapping
{
  "name": "product_viewed"
}
Out
optimizely.trackEvent("product_viewed", {})

Purchase revenue

An order fires an Optimizely purchase event with revenue in cents, value, and additional event tags.

Event
{
  "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"
  }
}
Mapping
{
  "name": "purchase",
  "settings": {
    "revenue": "data.revenue_cents",
    "value": "data.value",
    "eventTags": {
      "map": {
        "currency": "data.currency",
        "item_count": "data.item_count"
      }
    }
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "name": "signup",
  "settings": {
    "attributes": {
      "map": {
        "signup_method": "data.method",
        "referral_source": "data.source"
      }
    }
  }
}
Out
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 failed with code missing-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 failed with code missing-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 failed with code missing-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 failed with code missing-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 failed with code missing-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.

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.

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