Skip to main content

Versive.init(config?)

Creates a client with global configuration. Call once and reuse.
string
default:"https://www.getversive.com"
Origin the study loads from. Auto-detected in script-tag mode; you normally don’t set this.
boolean
default:"false"
Global preview mode — responses are not saved.
VersiveDisplayConfig
Default modal display options, merged with per-call options.
VersiveColors
Default colors for every study this client opens or embeds, merged with per-call colors.
Partial<VersiveCallbacks>
Default event callbacks. Both global and per-call callbacks fire.

versive.open(studyId, options?)

Opens a study in a modal overlay. Closes any previously open modal session. Returns a StudySession.
string
required
The study’s ID (from the study’s Launch → Embed tab, or study settings).
boolean
Preview mode for this session.
Record<string, string>
Key/value pairs attached to the response as metadata. Appended to the study URL as query parameters — don’t pass sensitive data. Keys embed, mode, textColor, primaryColor and backgroundColor are reserved and ignored with a console warning.
VersiveDisplayConfig
Modal display options for this session.
VersiveColors
Colors for this session. Each key overrides the one from init.
Partial<VersiveCallbacks>
Event callbacks for this session.

versive.embed(studyId, container, options?)

Embeds a study inline. Returns a StudySession. Throws if the container isn’t found. Inline embeds ignore display — the iframe fills the container’s width and auto-sizes its height.
string | HTMLElement
required
A CSS selector or element to render into.
options accepts preview, context, colors, and on (as above).

versive.close() / versive.destroy()

close() closes the active modal session. destroy() closes it and removes all listeners.

Display options

Modal-only, passed via display:

Colors

colors takes { text, primary, background }, each a 6-digit hex value like '#18181B'. Each key replaces the study’s own color for this embed only; a key you leave out keeps the study’s color. The modal and its loading screen use background too. A value that is not #RRGGBB is ignored with a console warning. The colors travel as reserved query parameters on the study URL (textColor, primaryColor, backgroundColor), and the study honors them only inside an embed. They style the study and are not stored with the response. Changing colors in the middle of an interview is not supported: pass the palette when you open or embed the study.

StudySession

Returned by open() and embed().

Events

Error codes

Loading behavior

The SDK shows a spinner while the study loads (inline embeds reserve a 600px placeholder until the first height report). If the study hasn’t loaded after 15 seconds, an error with code TIMEOUT fires and the session closes — most commonly because the host domain isn’t on the allowed embed domains list.