(Optional) KV store configuration

👍

Beta

Optimizely Edge Agent is in beta. Apply on the Optimizely beta signup page or contact your Customer Success Manager.

Optimizely Edge Agent is a powerful tool for leveraging Cloudflare Edge Workers for A/B testing and experimentation. The following guides you through deploying and configuring Optimizely Edge Agent for efficient datafile management and user profile data storage using the Cloudflare KV store.

Key Features

• Cloudflare KV store integration – Manage Optimizely Feature Experimentation datafiles and flag keys with reduced latency.
• Sticky bucketing decisions – Ensure returning visitors experience consistent experiment variations.
• Automated datafile management – Seamless updates through Optimizely webhooks.

Using Cloudflare KV Store for datafile management and user profile data

Benefits of KV Store

• Reduced latency – By storing datafiles in the KV store, you eliminate the need for external requests to the Optimizely CDN, significantly reducing fetch times.
• Selective Experiment Evaluation – Store only the necessary Flag Keys to control which experiments are evaluated, optimizing performance and resource usage.

Sticky bucketing decisions

Sticky bucketing ensures that returning visitors continue to see the same experiment variations, even if the traffic allocation or conditions change. This is achieved by storing user profile data in the KV store. For information, see Ensure consistent user bucketing.

Store flag keys

Store only the flag keys for experiments and targeted deliveries you must evaluate. For example, if the data file contains 20 flag keys but only five are stored in the KV store, only these five are evaluated. There is no need to create the keys in the KV namespace, as they are created by the agent if they do not exist, but the namespace must be found.

Configuring the KV store

To use the KV store, you must create two namespaces. These are defined in the defaultSettings.js file under the _config_ directory:

const defaultSettings = {  
     kv_namespace: 'OPTLY_HYBRID_AGENT_KV', // Namespace for datafile and flag keys storage.  
     kv_key_optly_flagKeys: 'optly_flagKeys',  // Key name for storing flag keys  
     kv_namespace_user_profile: 'OPTLY_HYBRID_AGENT_UPS_KV',  
 };

You can customize these names, but the constant names must remain unchanged. Optimizely Edge Agent manages multiple datafiles stored under the kv_namespace constant by their Optimizely datafile SDK key.

Flag keys storage

Flag keys are stored under a key (default: optly_flagKeys) as a comma-delimited string, for example:, "cloudflare_demo_flag,cloudflare_demo_flag_exp_2".

API for managing datafiles and flag keys

Optimizely Edge Agent implements an API to manage datafiles and flag keys in the KV store. The API code is located under the _api_ folder.

Routes

• Datafile route – /v1/api/datafiles/:key
• Flag keys route – /v1/api/flag_keys

Methods

Datafile Route

• POST – Expects a datafile SDK key as a parameter. Triggers the edge worker to fetch and update the datafile in the KV store.
• GET – Returns the current datafile stored in the KV store.

Flag keys route
POST – Expects a JSON payload with a flagKeys property containing an array of flags to be stored in the KV store.

Example payload:

{
    "flagKeys": [
        "cloudflare_demo_flag",
        "cloudflare_demo_flag_exp_2"
    ]
}

GET – Returns the current list of flag keys stored in the KV store as a JSON response.

Example response:

{
    "message": "Flag keys were updated successfully in the KV store.",
    "flagKeys": [
        "cloudflare_demo_flag",
        "cloudflare_demo_flag_exp_2"
    ]
}

Automatic datafile management with webhooks

An Optimizely webhook can be set up to automatically update the datafile in the KV store. When changes occur in the project datafile, the webhook triggers the edge worker to update the datafile without user intervention. For information, see Configure wehbooks.

Control the KV store usage

The behavior for using the KV store can be controlled through headers or query parameters.

Headers

• X-Optimizely-Flags-KV – Enable using flag keys from KV store.
• X-Optimizely-Datafile-KV – Enable using the datafile from the KV store.

Query Parameters

• enableDatafileFromKV – Enable using the datafile from KV store.
• enableFlagsFromKV – Enable using flag keys from KV store.

Example query parameters: /webpage.html?enableDatafileFromKV=true.

Body payload

Example body:

{
  "enableDatafileFromKV": true,
}

Configuration

Configuration values are defined in the requestConfig.js file in the _config_ directory. You can also define default values under the this.settings configuration object. Values from headers, query parameters, or JSON body payloads will override default values if set to true.

Create a Namespace in the KV Store

Creating a namespace in the Cloudflare KV store is straightforward and can be done through the Cloudflare dashboard or using the Wrangler CLI.

Using the Cloudflare Dashboard

1. Log in to your Cloudflare account.
2. Go to the Workers section.
3. Select "KV" from the sidebar.
4. Click Create namespace.
5. Enter the desired namespace name (for instance, OPTLY_HYBRID_AGENT_KV).
6. Click Create.

Using Wrangler CLI

1. Ensure Wrangler is installed and configured.
2. Run the following command to create a namespace:

 wrangler kv:namespace create "OPTLY_HYBRID_AGENT_KV"

For more details, refer to the Cloudflare KV's Get started documentation.