SDK reference - Versive

`Versive.init(config?)`

Creates a client with global configuration. Call once and reuse.

const versive = Versive.init({
  preview: false,
  display: { width: '480px' },
  on: { complete: handleComplete },
});

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.

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 and mode are reserved.

VersiveDisplayConfig

Modal display options for this session.

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, 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:

Option	Type	Default
`width`	`string`	`'480px'`
`maxHeight`	`string`	`'90vh'`
`closeOnOverlayClick`	`boolean`	`true`
`closeOnEscape`	`boolean`	`true`
`zIndex`	`number`	`999999`

`StudySession`

Returned by open() and embed().

Member	Description
`isOpen`	`boolean` — whether the session is currently open.
`on(event, handler)`	Subscribe to an event. Returns an unsubscribe function.
`off(event, handler)`	Unsubscribe a handler.
`close()`	Close the session (tears down the iframe/modal).
`destroy()`	Close and remove all event listeners.

Events

Event	Payload	Fires when
`ready`	—	The study has loaded and the loader is hidden.
`start`	`{ interviewId }`	The participant begins the study.
`complete`	`{ interviewId, responseId }`	The participant finishes.
`heightChange`	`height` (number)	The study content resized (inline auto-height).
`close`	`reason` — `'completed' \| 'dismissed' \| 'error'`	The session closed.
`error`	`{ code, message }`	Something went wrong.
`permissionRequired`	`'microphone' \| 'camera'`	Reserved for voice/video permission prompts — treat as experimental.

Error codes

Code	Meaning
`TIMEOUT`	The study didn’t load within 15 seconds. The session auto-closes.
`SUBMISSION_ERROR`	A response failed to submit inside the study.

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.

​Versive.init(config?)

​versive.open(studyId, options?)

​versive.embed(studyId, container, options?)

​versive.close() / versive.destroy()

​Display options

​StudySession

​Events

​Error codes

​Loading behavior