@optimizely/edge-delivery

Optimizely Edge Delivery SDK

Optimizely Edge Delivery lets you execute Optimizely Web experiments on Cloudflare Workers.

---

Prequisites

• You must have a Cloudflare Account.
• You must install the Wrangler CLI.

Implementing in an existing Worker

You can install the Optimizely Edge Delivery SDK in any existing Cloudflare Worker, whether you already route your incoming traffic through a Cloudflare Worker, or you'd prefer to start from scratch using Cloudflare's getting started guide.

Installing the Edge Delivery SDK

Install the Edge Delivery library using npm:

npm install @optimizely/edge-delivery

Implementing and executing experiments

The SDK accepts a config object options with the following properties:

• options.snippetId: string | number - A Snippet ID for pointing to the generated Edge-Delivery configuration file.
• options.accountId: number | undefined - An optional Account ID for injecting custom snippets, ie. cdn.optimizely.com/public/${accountId}/s/${snippetId}/web_sdk_v0.json
• options.isProd: boolean | undefined - Whether this is production environment. Defaults to true.
• parsedOptions.isSnippetless: boolean | undefined - Whether to run Edge-Delivery in snippetless mode, which does not inject any snippet on the page. This only supports experiments with only page-level transforms and dont require any browser-level transforms, as it will not compile any Javascript necessary for executing any remaining functionality on the browser. Defaults to false.
• options.nonce: string | undefined - An optional nonce value for the injected snippet script tag.
• options.position: string | undefined - An optional parameter on where to place the injected snippet with an element(ie. or ). Possible values are 'top' (inject into beginning of head) or 'bottom' (inject into end of head). Defaults to 'top';
• options.cacheTTLs: number | undefined - An optional object that contains targetTTL, dataTTL, browserTTL. Defaults to 0.
• options.deployId: string | undefined - An optional parameter that is used for calculating the cache string. A cache HIT means the BrowserJS is cached and will be returned immediately. Defaults to null.
• options.fallback: string | undefined - An optional parameter that controls behavior if there is an error thrown in edge rewriter. Defaults to null. Can have the following values:
  • error: Throws the error, which should show up in the worker logs, before proceeding on to the "snippet" logic below.
  • snippet: Returns the web snippet injected page, essentially bypassing Edge-Delivery and falling back to normal web snippet operation. If this fails, proceeds to "null" logic below.
  • null: Returns the original request.
• options.existingSnippet: string | undefined - An optional parameter that controls what to do if an existing snippet is encountered on the page. Defaults to 'keep'. Can have the following values:
  • keep: Does nothing to the existing snippet on the page.
  • comment: Injects an HTML comment tag around the existing snippet tag on the page.
  • remove: Removes the existing snippet tag on the page entirely.
• options.control: Response | undefined - The response from the original page request, before any transformations are applied.
• options.rewriter: HTMLRewriter | undefined - An optional input for defining a custom trasnformation HTMLRewriter class.
• options.environment: 'dev' | 'prod' - A mandatory option to define in what environment the worker will run
• options.dev_host: string | undefined - An optional string, whether the target request is in a development url. if it is not provided, by default the target request host is example.com.
• options.dev_protocol: string | undefined - An optional string, whether the target request protocol is in a development url. if it is not provided, by default the target request protocol is https
• options.dev_port: string | undefined - An optional string, whether the target request port is in a development url (ie. 8080).
• options.dev_pathname: string | undefined - An optional string, whether the target pathaname request is in a development url (ie. hello/world). if the pathname is not provided. the pathname value could ve the pathname of the current request (ie. localhost/hello/world). the pathname will be hello/world
• options.DATA - the JSON configuration file to retrieve to execute your experiments.

Basic configuration options

It's recommended to set a Development URL (devUrl) for the SDK to use as a target when testing locally or at your worker site directly.

const options = {
    "snippetId": "29061560280",
    "dev_host": "example.com"
};

applyExperiments

The applyExperiments method is used to execute experiments. This method uses the request information to make experiment bucketing decisions and apply active experiment variations to the control. Any decisions or changes that cannot be made on the edge are packaged together and added to the <head> element for execution on the browser.

import { applyExperiments } from '@optimizely/edge-delivery';
...
await applyExperiments(request, ctx, options);

Other configuration options

Optionally, you may pass a Response object as the control in the options parameter. This can be useful if you already have an existing Cloudflare Worker that, for example, makes modifications to the control outside of Optimizely experiments.

let control = await fetch(request);
...
const options: Options = {
    // Other options
    "control": control
};