Embed an interview inside your product

Add an in-product survey embed with the Versive SDK: modal or inline, zero-code attributes, and the domain security to set up first.

An in-product survey embed puts a Versive study, whether a survey, an AI-moderated interview, or a mix of both, directly inside your app. @getversive/embed is a lightweight JavaScript SDK that renders the study in a secure iframe and handles modal or inline presentation.

What @getversive/embed does

@getversive/embed is a zero-dependency wrapper of about 4 KB gzipped. It creates the iframe, shows a loading state, and relays a small set of postMessage events between your page and the study. All study logic, AI moderation, branding, and response storage stay server-side on Versive's origin. The SDK never touches study content or handles API keys in the browser. It needs only the public study ID, while a separate domain allow-list controls access.

Install it as an npm package for programmatic control, or use a script tag and HTML data attributes without writing JavaScript.

Modal or inline: pick a pattern

The SDK supports two ways to surface a study. Choose based on when you want feedback.

Modal (versive.open) overlays the study on the current page. Use it after a specific event, such as checkout, subscription cancellation, or a person's first use of a feature. Only one modal session runs at a time.

Inline (versive.embed) renders the study inside a container element on the page, and the iframe auto-resizes as the participant progresses. It fits a dedicated feedback page, a settings panel, or an embedded research widget where the study is content on the page rather than an interruption. Multiple inline embeds can coexist on one page.

const versive = Versive.init();

// Modal, opened on some trigger in your app
versive.open('study-id', { display: { width: '560px' } });

// Inline, rendered into a container
versive.embed('study-id', '#feedback-container');

Installing the SDK

For apps with a build step, install the package and initialize it once:

npm install @getversive/embed

import Versive from '@getversive/embed';

const versive = Versive.init();

To avoid adding a package dependency, load the script tag. It exposes a global Versive class and scans the page for embed attributes:

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

Zero-code embedding with data attributes

With the script tag loaded, add a data-versive-study attribute to any element to embed a study without JavaScript. The SDK also watches for dynamically added elements, so this works in single-page apps.

<!-- Renders inline -->
<div data-versive-study="your-study-id"></div>

<!-- Opens in a modal when clicked -->
<button data-versive-study="your-study-id" data-versive-mode="modal">
  Give feedback
</button>

This option lets you test an in-product survey embed on a marketing site, a docs page, or anywhere you do not control the JavaScript bundle.

Passing context to identify participants

Use context to attach values such as a user ID, plan, or experiment cohort to the response, so you can join it to your product data afterward:

versive.open('study-id', {
  context: { userId: 'user_123', plan: 'pro', cohort: '2026-07' },
});

Context values are appended to the study URL as query parameters, so treat them as visible to the participant. Use an opaque internal ID rather than an email, name, or token, and never pass anything sensitive.

Security: domains and content policies

Embedding is off by default. An organization admin must add your site's domain to the allowed embed domains list in Versive settings before a study will render. Until then, the SDK returns a TIMEOUT error. Add every origin you use, including staging and localhost. The allow-list is enforced server-side, so a public study ID cannot render on an unapproved origin.

If your site sets a Content Security Policy, allow the Versive frame:

Content-Security-Policy: frame-src https://getversive.com https://www.getversive.com;

Voice and video studies additionally need the browser to delegate microphone and camera access to the iframe. The SDK sets allow="microphone; camera" on the iframe automatically, but if you set a Permissions-Policy header, it needs to include the Versive origin as well, or those studies won't get device access. See Security & domains for the full policy and for how the origin-validated postMessage bridge works in both directions.

When in-product beats email

Use email links to recruit outside customers, run a study with a purchased panel, or reach people who are not currently in your product. Use an in-product embed when feedback should be tied to a specific moment in the user's session without sending them to their inbox.

Triggering a modal after checkout, after a cancellation, or on the third use of a feature captures feedback close to the event. The context value can associate the response with an opaque user record without later matching responses to users. The complete event can notify your backend that a response is ready for verification, but it must not authorize an incentive on its own.

Reacting to the study lifecycle

Both open and embed return a session you can listen to, which is useful for dismissing prompts, logging completion in your own analytics, or asking your backend to verify a response before granting an incentive:

const session = versive.open('study-id', { context: { userId } });

session.on('complete', async ({ interviewId, responseId }) => {
  await requestVerifiedIncentive({ interviewId, responseId });
});

session.on('close', (reason) => {
  // 'completed' | 'dismissed' | 'error'
});

Treat context, interviewId, responseId, and the callback itself as untrusted browser input. The authenticated backend endpoint should load the persisted response, confirm that it completed the expected study, bind it to the authenticated user, and make the incentive grant idempotent. Never issue payment based only on the client event.

The Embedding studies docs list all events and methods and explain preview mode for testing embeds without saving real responses.

To compare embeds with share links, email outreach, and panels, see How to recruit research participants (4 ways). For format selection, see Text, voice, or video: choosing an interview mode. If participants will receive a reward, review Research incentives: what to pay participants before wiring up the complete event.