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 returns the same instance.

app.ts

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

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 surveys.
`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.

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? }) — update settings at runtime
client.load() — manually start the widget when disableAutoLoad is true
client.close() — close any open flow

Flows

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

Observation

client.track(eventName, properties?, options?) — track a product event with optional external IDs
client.subscribeFlowState(callback, options?) — watch flow state changes
client.onOpenRequested(callback) — observe open requests before the flow renders
client.setDefaultContainerPolicy(policy) — control default container behavior

Events

We recommend sending product events server-side through an integration such as Segment. If client-side tracking fits your app better, client.track(eventName, properties?, options?) records an event from the browser.

client.track("Checkout Started", {plan: "pro",source: "billing_page",});

You can call track() before or after login. When the same person is later identified, Identity resolution merges their events into a single profile. See Events for reference.

Use options.externalIds when an identify or track call carries an identifier from another system, such as a Shopify customer ID. External IDs help match profiles, but they are not traits by themselves. Do not put Segment-shaped externalIds in traits or event properties.

await client.identify("user_123", { email: "jane@example.com" }, {externalIds: [{id: "gid://shopify/Customer/123",type: "shopify_customer_id",collection: "users",encoding: "none",},],});client.track("Checkout Started", { plan: "pro" }, {externalIds: [{id: "gid://shopify/Customer/123",type: "shopify_customer_id",collection: "users",encoding: "none",},],});

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 Opening surveys from code for usage patterns, Response metadata for metadata examples, and Containers for custom container examples.