JavaScript SDK reference

Everything revolves around one client created with createClient(). If you haven't set up yet, start with the JavaScript SDK guide.

createClient(options)

Create a single client and reuse it across your app. Calling createClient again with the same apiKey, initial flags, initial capabilities, and static action definitions returns the same instance.

app.ts

import { createClient } from "@getuserfeedback/sdk";const client = createClient({ apiKey: "YOUR_API_KEY" });

If the current app version supports a newly shipped feature, report that with capabilities:

app.ts

const client = createClient({apiKey: "YOUR_API_KEY",capabilities: ["checkout.drawer"],});

Options

Option	Type	Default	Description
`apiKey`	`string`	required	Your project API key.
`colorScheme`	`"light" \| "dark" \| "system" \| { autoDetectColorScheme: string[] }`	auto-detect	Color scheme. See Dark mode.
`defaultConsent`	`"granted" \| "pending" \| "denied" \| "revoked" \| GrantScope[]`	`"granted"`	Initial consent state. See Privacy & consent.
`disableAutoLoad`	`boolean`	`false`	When `true`, call `client.load()` manually before opening flows.
`disableTelemetry`	`boolean`	`false`	Disables anonymous performance telemetry. Does not affect user analytics.
`flags`	`Record<string, AppEventFlagValue> \| AppEventFlag[]`	none	Your app's feature flag evaluations. Used by rolling theme updates.
`capabilities`	`Array<string \| AppEventCapability>`	none	What the current app version can support. Used by capability conditions.
`actions`	`ActionRegistration[]`	none	Static custom actions and an optional webpage-navigation override.

Actions (`actions`)

Register custom actions and optional browser URL handling through actions. Definitions remain fixed after loading starts, while matching handler functions can be refreshed. See Actions for setup and behavior.

Client methods

Identity

client.identify(userId, traits?, options?) — associate a user ID, traits, and optional external IDs with the current user
client.identify(traits, options?) — associate traits with the current user
client.identify(traits, undefined, options?) — three-argument form for call sites that keep options separate
client.reset() — clear identity and auth state on logout

Configuration

client.configure({ colorScheme?, consent?, auth?, capabilities? }) — update settings at runtime
client.load() — manually start the widget when disableAutoLoad is true
client.close() — close any open flow

Use capabilities when the supported capabilities become known or change after the widget has loaded:

client.configure({capabilities: ["checkout.drawer", "messages.compose.v2"],});

The widget checks for newly eligible flows after capabilities change. See Capabilities.

Flows

client.flow(flowId) — get a reusable flow handle (see below)
client.flow(flowId).open(options?) — open a flow
client.flow(flowId).prefetch() — load flow resources over the network
client.flow(flowId).prerender(options?) — warm up the UI before opening

Observation

client.track(eventName, properties?, options?) — track a product event with optional external IDs
client.page(name?, properties?, options?) — record a browser page or web location. See Events.
client.graph.connect(relationship) — record that two product objects are connected
client.graph.disconnect(relationship) — record that the connection ended
client.subscribeFlowState(callback, options?) — watch flow state changes
client.onOpenRequested(callback) — observe explicit SDK and client-side targeting opens before the flow renders
client.setDefaultContainerPolicy(policy) — control default container behavior

Events

Use client.track() for product actions and client.page() for browser page or web locations. See Events for the shared argument rules and examples.

Relationships

Use client.graph to record connections between users, accounts, workspaces, projects, or other product objects. Each endpoint needs a collection key and a stable ID.

const relationship = {from: { collection: "user", id: "user_123" },to: { collection: "account", id: "acct_456" },};await client.graph.connect(relationship);await client.graph.disconnect(relationship);

These methods record ordinary analytics observations. A disconnect ends the connection established by earlier observations; a later connect can establish it again. Collection keys use lowercase kebab-case, such as user or property-manager, and IDs must be nonblank. Invalid relationship properties remain ordinary analytics events but do not update the graph. See Groups for audience behavior and current limitations.

Flow handle

client.flow(flowId) returns a reusable handle for one specific flow. Use it when you want to prefetch, prerender, and open as part of one lifecycle.

feedback-button.ts

const flow = client.flow("YOUR_FLOW_ID");flow.prefetch();flow.prerender();flow.open();

Fire-and-forget vs awaiting

open(), prefetch(), prerender(), and close() return promises, but you do not have to await them for the widget to behave correctly.

The widget manages its own execution queue internally, so both of these approaches work:

flow.prefetch();flow.prerender();flow.open();

and:

await flow.prefetch();await flow.prerender();await flow.open({metadata: {tags: {journey_stage: "onboarding",},},});

Use fire-and-forget when you just want the widget to do the work. Use await when your app logic needs to know that a step finished before doing something else.

Methods

open(options?) — open the flow (options include container, metadata, and hideCloseButton)
prefetch() — load resources over the network
prerender() — warm up the UI
close() — close the flow
setContainer(element | null) — attach or detach a custom container
getFlowState() — get the current state
subscribeFlowState(callback, options?) — watch state changes

See Open Widget flows from code for usage patterns, Response metadata for metadata examples, and Containers for custom container examples.