The BlueConic Web SDK helps developers connect web-based apps to BlueConic. It is intended for apps that run in a browser environment, such as single-page applications, smart TV apps built with web technology, and WebView-based experiences.
If you are implementing the SDK in a ChatGPT App, see Using the BlueConic Web SDK in a ChatGPT App.
BlueConic Web SDK or JavaScript front-end API?
Use the BlueConic Web SDK when you are building an app in a web environment.
Use the JavaScript front-end API when you are working with a website where the BlueConic tag is loaded on the page.
The main differences are:
BlueConic Web SDK | JavaScript front-end API |
Best fit for app-like experiences in a web environment | Best fit for websites and webpage integrations |
Used when your team controls the app flow and decides when screens and events are sent to BlueConic | Used when BlueConic is already present on the webpage through the BlueConic tag |
Intended for experiences such as single-page apps, smart TV apps built with web technology, WebViews, and ChatGPT Apps | Intended for websites where BlueConic runs as part of the webpage |
Before you begin
Before you start implementing the SDK, make sure that:
Your app runs in an environment with access to `window`, `document`, `fetch`, and `localStorage`.
Your BlueConic app setup is enabled.
You know your BlueConic tenant base URL.
The profile properties, objectives, interactions, dialogues, listeners, and recommendation stores you want to use are already configured in BlueConic.
Getting started
Note: The latest SDK version is 1.0.0.
Install the BlueConic Web SDK package from npm:
npm install @blueconic/blueconic-web-sdk
Then import the SDK and retrieve the shared client instance:
import blueConicClient from "@blueconic/blueconic-web-sdk";
Note: To determine the latest version, see https://www.npmjs.com/package/@blueconic/blueconic-react-native?activeTab=versions.
Initialize the SDK before making any other SDK API calls:
await blueConicClient.initialize({
hostName: "https://yourtenant.blueconic.net"
});
If you want to override the referrer value sent to BlueConic, you can also provide `overrideAppId`:
await blueConicClient.initialize({
hostname: "https://yourtenant.blueconic.net",
overrideAppId: "your-app-id"
});
Important:
Initialization is asynchronous and depends on network calls
Initialization can fail because of connectivity, timeout, or server issues
Your app should await initialization before using event creation, profile, recommendation, or timeline APIs
Your app should implement a retry or fallback strategy so the SDK can still become available later in the same user session
Using the BlueConic Web SDK
Understanding API behavior
Most Web SDK operations that communicate with BlueConic return a `Promise` and should be awaited.
await blueConicClient.createPageViewEvent("Home");
The event API can be used to subscribe and unsubscribe from events:
const subscriptionId = blueConicClient.event.subscribe("onReady", null, () => {});
blueConicClient.event.unsubscribe(subscriptionId);
Create a page view event
Create a page view event whenever the user arrives on a new screen in your app.
await blueConicClient.createPageViewEvent("Home");
You can include additional properties if needed:
await blueConicClient.createPageViewEvent("Product Details", { productId: "sku-123" });
Notes:
You should still create explicit page view events for the screens in your app
Make sure that a unique screen name is passed in the call
In a single-page application, call `createPageViewEvent()` when the route changes
Configure consent
The SDK supports privacy legislation, consented objectives, refused objectives, and permission levels.
await blueConicClient.profile.setPrivacyLegislation("GDPR");
blueConicClient.profile.permission.setLevel(blueConicClient.profile.permission.levels.PERSONAL);
These changes are not persistent until `updateProfile()` is called.
You can scope permission updates to specific profile properties or plugin IDs:
blueConicClient.profile.permission.optin.addProfileProperty("email");
To retrieve the current consent-related values:
const privacyLegislation = blueConicClient.profile.getPrivacyLegislation();
const permissionLevel = blueConicClient.profile.permission.getLevel();
Create BlueConic events
Use the create-event API when BlueConic itself should process the event:
await blueConicClient.createPageViewEvent("homepage");
await blueConicClient.createViewEvent("interaction-id");
await blueConicClient.createClickEvent("interaction-id");
await blueConicClient.createConversionEvent("interaction-id");
For custom BlueConic event types, use `createEvent()`:
await blueConicClient.createEvent("video_started");
You can also pass the event context directly:
await blueConicClient.createEvent("article_finished", { articleId: "story-42" });
Create a timeline event
Use timeline events when you want to send timestamped events to BlueConic.
await blueConicClient.createTimelineEvent("subscription_started", new Date(), { plan: "premium" });
If you already have your own timeline event ID, use `createTimelineEventById()`:
await blueConicClient.createTimelineEventById("timeline-event-123", "purchase", new Date(), { orderId: "order-123" });
Gather profile information
When the SDK first interacts with BlueConic, a profile is created or retrieved. To get the current profile ID:
const profileId = blueConicClient.profile.getId();
To retrieve the current profile properties:
const properties = blueConicClient.profile.getProperties();
To update profile properties:
await blueConicClient.profile.setValue("favorite_category", "sports");
await blueConicClient.profile.addValue("favorite_category", "reading");
await blueConicClient.profile.incrementValue("score", 1);
Important:
`getProperties()` returns the current profile properties available in the SDK
`set()`, `add()`, `increment()`, and consent-related changes schedule an automatic sync to BlueConic
Call `updateProfile()` when you want to force an immediate sync and refresh
To retrieve a fresh property snapshot from BlueConic:
const refreshedProperties = await blueConicClient.profile.refreshProperties();
To explicitly manage the profile lifecycle:
await blueConicClient.createProfile();
await blueConicClient.deleteProfile();
Publish events
Use the event manager when the event should stay local to your app and only be picked up by subscribed handlers:
blueConicClient.event.publish("playerStateChanged", { state: "playing" });
blueConicClient.event.publishAdvancedEvent("videoStarted", ["hero", "autoplay"]);
blueConicClient.event.publishClickEvent("#hero-cta", ["homepage"]);
blueConicClient.event.publishFormSubmitEvent("#signup-form", ["newsletter"]);
blueConicClient.event.publishUpdateContentEvent("<h1>Welcome</h1>", "#dialogue-root");
blueConicClient.event.publishUpdateValuesEvent("#email", ["[email protected]"]);
Subscribing to events
The SDK includes an event API for SDK lifecycle events, dialogue events, and custom events.
const subscriptionId = blueConicClient.event.subscribe("onReady", () => {});
To unsubscribe:
blueConicClient.event.unsubscribe(subscriptionId);
Notes:
Event names are case-insensitive
The event name passed to your callback is normalised to lowercase
The callback receives `(eventName, payload)`
If you are waiting for page-view-driven dialogue or plugin events, subscribe before triggering the page view or event that should produce them
`unsubscribe()` accepts either the numeric subscription ID or an event name token
Plugins and dialogues can also publish events.
Example:
blueConicClient.event.subscribe("propertiesDialogue", (_eventName, payload) => {
console.log(payload);
});
Test the SDK integration
Enable debug mode
To enable extra logging, pass `debugMode: true` during initialisation:
await blueConicClient.initialize({
hostName: "https://yourtenant.blueconic.net",
debugMode: true
});
Note: Debug mode provides additional logging and enables simulator-related behaviour.
Warning: When you publish your apps, Debug should always be set false.
Use simulator data
If you are testing with the BlueConic Simulator and already know the simulator username and session ID, you can pass that data during initialization:
await blueConicClient.initialize({
hostName: "https://yourtenant.blueconic.net",
debugMode: true,
simulator: {
userName: "simulator-user",
sessionId: "session-id"
}
});
Release Notes
To see a list of updates and bug fixes for the SDK, see the BlueConic SDK for Web Release Notes.