@getversive/embed

Embed Versive studies (surveys, AI interviews) in any web app. Lightweight (~4KB gzipped), framework-agnostic, zero dependencies.

Quick Start

Script Tag (Zero-Code)

<script src="https://getversive.com/embed.js"></script>

<!-- Inline study -->
<div data-versive-study="YOUR_STUDY_ID" data-versive-mode="inline"></div>

<!-- Button that opens modal -->
<button data-versive-study="YOUR_STUDY_ID" data-versive-mode="modal">
  Share Feedback
</button>

JavaScript SDK

npm install @getversive/embed

import Versive from '@getversive/embed';

// Initialize once — use anywhere in your app
const versive = Versive.init();

// Open a study as a modal
versive.open('YOUR_STUDY_ID', {
  context: {
    userId: 'user_123',
    plan: 'enterprise',
  },
  on: {
    ready:    () => console.log('Study loaded'),
    start:    (data) => console.log('Started:', data.interviewId),
    complete: (data) => console.log('Done:', data.responseId),
    close:    (reason) => console.log('Closed:', reason),
    error:    (err) => console.error(err),
  },
});

// Or embed inline
versive.embed('YOUR_STUDY_ID', '#feedback-container');

Display Modes

Modal

Opens the study in a centered overlay with backdrop, close button, escape key, and click-outside-to-close.

const versive = Versive.init();

versive.open('abc123', {
  display: {
    width: '480px',
    maxHeight: '90vh',
    closeOnOverlayClick: true,
    closeOnEscape: true,
    zIndex: 999999,
  },
});

Inline

Embeds the study directly in a container element. The iframe height auto-adjusts to match content.

const versive = Versive.init();

const session = versive.embed('abc123', '#my-container', {
  on: {
    heightChange: (height) => console.log('New height:', height),
  },
});

API Reference

Versive.init(config?)

Creates a Versive client with global configuration. Call once, use everywhere.

versive.open(studyId, options?)

Opens a study in a modal overlay. Returns a StudySession for event subscriptions.

versive.embed(studyId, container, options?)

Embeds a study inline in a container (CSS selector or HTMLElement). Returns a StudySession.

versive.close()

Closes the active modal session.

versive.destroy()

Destroys the client and cleans up all resources.

StudySession Methods

The open() and embed() methods return a StudySession for direct control:

Display Options

Events

Data Attributes (Script Tag)

Content Security Policy

If your site uses a CSP, add the Versive domain to frame-src:

frame-src https://getversive.com;

For voice/video studies, ensure your Permissions-Policy allows microphone and camera for the Versive domain.

Supported Study Modes

• Text surveys — Standard form-based surveys
• AI interviews (voice + video) — Conversational AI with microphone/camera. The SDK automatically sets allow="microphone; camera" on the iframe.

Preview Mode

Pass preview: true (SDK) or add data-versive-preview (script tag) to run the study without saving responses. This uses the same preview mode as the study editor.

Development

npm install
npm run build     # Build IIFE + ESM bundles
npm run dev       # Watch mode
npm run type-check

Build outputs:

• dist/embed.js — IIFE bundle (for <script> tag)
• dist/embed.min.js — Minified IIFE
• dist/embed.esm.js — ES module (for import)
• dist/index.d.ts — TypeScript declarations

Architecture

The SDK is a thin client-side wrapper (~4KB gzipped) that manages:

1. iframe creation — Loads the study at {baseUrl}/s/{studyId}?embed=true
2. postMessage bridge — Namespaced versive:* messages with origin validation
3. Modal rendering — Backdrop, close button, escape key, animations
4. Inline rendering — Auto-height via versive:heightChange messages
5. Loading state — Spinner with 10-second timeout

All study logic, AI moderation, and branding live server-side inside the iframe. The SDK never touches study content.