This guide explains how to use the BlueConic Web SDK inside the custom UI component of an existing ChatGPT App.
For general information about the SDK, see the BlueConic SDK for Web.
This guide focuses on the widget side of the integration. For more information about profile properties, timeline events, recommendations, and events, see the main SDK document.
In a ChatGPT App, use the BlueConic Web SDK. A ChatGPT App is an app experience, not a website where the BlueConic tag is loaded on the page.
Before you begin
Before you start, make sure that:
You already have a ChatGPT App with a custom UI component.
You set up your BlueConic tenant.
You have decided which screens, interactions, profile properties, and timeline events in the ChatGPT App should be tracked in BlueConic.
Your ChatGPT App configuration allows the widget to make requests to the BlueConic tenant.
Using the BlueConic Web SDK in the widget
Initialize the SDK once
Initialize the SDK in the widget and reuse the same client instance.
Install the package in the widget project:
npm install @blueconic/blueconic-web-sdk
import blueConicClient from "@blueconic/blueconic-web-sdk";
await blueConicClient.initialize({ hostName: "https://yourtenant.blueconic.net" });
Notes:
Initialize the SDK once per widget instance.
Await initialization before using event creation, profile, recommendation, or timeline APIs.
If initialization fails, handle that in the widget without blocking the rest of the ChatGPT App UI.
Use app state with the SDK
In a ChatGPT App, app state such as the current screen, selected item, prompt text, authentication state, or display mode can be used to decide when to create BlueConic events or update profile properties.
Create page view events for screens in the app
Create a page view event when the widget opens and whenever the user reaches a new screen in the ChatGPT App.
await blueConicClient.createPageViewEvent("chatgpt/shop/app-opened");
You can also create page view events for additional screens or content states:
await blueConicClient.createPageViewEvent("chatgpt/shop/content-viewed", { displayMode: "fullscreen" });
Notes:
Use stable screen names.
Avoid creating duplicate page view events for the same screen.
Update profile properties from app context
In a ChatGPT App, profile properties can be updated from values that are already available in the widget.
await blueConicClient.profile.setValue("chatgpt_display_mode", "fullscreen");
Note:
Profile changes are scheduled for automatic persistence.
If you collect prompts or user identifiers from the app context, decide first whether those values should be stored in profile properties.
Only store values that fit your BlueConic data model and privacy requirements.
ChatGPT App considerations
CSP
The widget runs inside a sandboxed iframe. Make sure the ChatGPT App allows requests to the BlueConic tenant.
For this SDK, the BlueConic tenant should be allowed in:
`connectDomains`
`resourceDomains`
This is important because the SDK sends requests to the BlueConic tenant and can also load BlueConic scripts and templates from that same tenant.
Widget state
If your widget uses app state or `window.openai.widgetState`, use that state to control when tracking happens.
For example:
Track a page view only when a new screen becomes active
Update profile properties when the selected item changes
Avoid sending duplicate events when the widget re-renders with the same state
Storage
The SDK stores BlueConic profile identifiers in `localStorage`. In a ChatGPT App, the stored profile context is scoped to the widget origin.
If the widget origin changes, treat that as a storage boundary for BlueConic profile persistence.