Javascript (Web)

Overview

This SDK provides a small JavaScript client that talks directly to the Neon Blue API and wraps the core calls you need for on-site experiments. Once initialized with a user identifier, the client returns the experiment value that has already been selected for that user by Neon Blue's backend models (for example, a banner image URL or other structured fields).

Setup the SDK

Install the SDK

Install

npm install @neonblue-ai/js-client

Initialize the SDK

Import and initialize the client once at application startup (for example, in your main entry file or app bootstrap). Pass your Neon Blue SDK key, a user object with a stable identifier, and optional configuration:

import NeonBlueClient from "@neonblue-ai/js-client";

const client = new NeonBlueClient(
  "client--00000000-0000-0000-0000-000000000000",
  { userId: "00000000" }
);

await client.initializeAsync();

The userId is used by Neon Blue's models to pick the correct variant for that specific user. For testing in our staging environment:

const client = new NeonBlueClient(
  "client--00000000-0000-0000-0000-000000000000",
  { userId: "00000000" },
  {
    networkConfig: {
      api: "https://api.staging.neonwhite.dev/v1/sdk",
    },
  }
);

Note: A React library is also available and wrap this same client for use in component trees. See the React section of the docs for details.

Use the SDK

Getting an Experiment

Use getExperimentAsync to fetch the rendered value for a given experiment key:

const experiment = await client.getExperimentAsync("my_experiment");
const value = experiment.get(
  "img_url",
  "https://fallback.example.com/default.jpg",
);

The SDK uses a cache-first strategy for retrieving experiments:

1

Check cache

Checks if the experiment exists in cache (from initialization).

2

Cache hit

If cache hit: returns cached result.

3

Cache miss

If cache miss: fetches from the network.

For each call:

• The backend selects the appropriate variant for the current userId.

• The SDK returns an Experiment object with a .get(key, fallback) method to retrieve fields.

• For simple banner tests, this often includes an image URL that is already hosted on Neon Blue's CDN and ready to render directly on the page.

You can also pass an optional render context for cache-miss network requests:

const experiment = await client.getExperimentAsync("my_experiment", {
  pageType: "landing",
  timestamp: Date.now(),
});

Changing Users

When a user logs in, update the client with the new user:

await client.updateUserAsync({ userId: "user-123" });

When a user logs out, pass an empty object to revert to anonymous mode (uses auto-generated StableId):

await client.updateUserAsync({});

A synchronous version is also available:

client.updateUserSync({ userId: "user-123" });