Embed API Reference

Quick Start

<div data-perspective-widget="RESEARCH_ID"></div>
<script src="https://getperspective.ai/v1/perspective.js"></script>

Embed Types

Type	Attribute	Element	Description
Widget	data-perspective-widget	<div>	Inline embed that renders directly in the page flow.
Popup	data-perspective-popup	<button>	Modal overlay centered on screen.
Slider	data-perspective-slider	<button>	Side panel that slides in from the edge.
Float	data-perspective-float	<div>	Floating chat bubble anchored to the corner.
Fullpage	data-perspective-fullpage	<div>	Full-viewport interview experience.

Examples

<div data-perspective-widget="RESEARCH_ID"></div>

<button data-perspective-popup="RESEARCH_ID">
  Share your feedback
</button>

<div data-perspective-float="RESEARCH_ID"></div>

URL Parameters

<div
  data-perspective-widget="RESEARCH_ID"
  data-perspective-params="source=homepage,user_id=123,plan=pro"
></div>

Built-In Parameters

Parameter	Type	Description
email	string	Pre-fill participant email.
name	string	Pre-fill participant name.
returnUrl	URL	Redirect URL after interview completion.
voice	"0"	Set to "0" to disable voice mode (text-only).
scroll	"0"	Set to "0" to disable scroll mode.
hideProgress	"true"	Hide the progress bar.
hideGreeting	"true"	Hide the welcome greeting at the start.
hideBranding	"true"	Hide the branding header (logo and company name).
enableFullScreen	"true" / "false"	Show or hide the fullscreen button. Defaults to "true".

Theming

Color Mode

<div
  data-perspective-widget="RESEARCH_ID"
  data-perspective-theme="dark"
></div>

Brand Colors

<div
  data-perspective-widget="RESEARCH_ID"
  data-perspective-brand="primary=#7c3aed,bg=#ffffff"
  data-perspective-brand-dark="primary=#a78bfa,bg=#1a1a1a"
></div>

Token	Description
primary	Primary accent color (buttons, links).
secondary	Secondary accent color.
bg	Background color override.
text	Text color override.

Auto-Open (Popup Only)

<div
  data-perspective-popup="RESEARCH_ID"
  data-perspective-auto-open="timeout:5000"
  data-perspective-show-once="session"
  style="display:none"
></div>

• timeout:N -- Opens the popup after N milliseconds.
• exit-intent -- Opens when the user moves their cursor toward the browser chrome (desktop only).

• session -- Show once per browser session.
• visitor -- Show once per visitor (persisted in localStorage).
• false -- Show every time.

JavaScript API

// Create an inline widget
const widget = Perspective.createWidget(container, {
  researchId: "RESEARCH_ID",
  params: { source: "app", user_id: "123" },
  onReady: () => console.log("Loaded"),
  onSubmit: () => console.log("Completed"),
  onNavigate: (url) => window.location.href = url,
  onClose: () => console.log("Closed"),
  onError: (err) => console.error(err),
});

// Open a popup
const popup = Perspective.openPopup({
  researchId: "RESEARCH_ID",
  onClose: () => console.log("Closed"),
});

// Open a slider
const slider = Perspective.openSlider({
  researchId: "RESEARCH_ID",
});

// Create a floating chat bubble
const float = Perspective.createFloatBubble({
  researchId: "RESEARCH_ID",
});

// Destroy an instance when done
widget.destroy();

Callbacks

Callback	Arguments	Description
onReady	--	Embed has loaded and is ready for interaction.
onSubmit	--	Participant completed the interview.
onNavigate	url: string	Embed requests a page navigation. If not provided, defaults to window.location.href (full page reload).
onClose	--	User closed the embed (popup, slider, or float).
onError	error: Error	An error occurred during the embed lifecycle.

Direct Iframe Embed

<iframe
  id="perspective-iframe"
  src="https://getperspective.ai/i/RESEARCH_ID?email=user@example.com&returnUrl=https://example.com/thanks"
  style="width: 100%; height: 600px; border: none;"
  allow="microphone"
></iframe>

var iframe = document.getElementById("perspective-iframe");
var allowedOrigin = new URL(iframe.src).origin;

window.addEventListener("message", (event) => {
  if (event.origin !== allowedOrigin) return;
  if (!event.data?.type?.startsWith("perspective:")) return;

  switch (event.data.type) {
    case "perspective:ready":
      // Embed loaded and ready
      break;
    case "perspective:submit":
      // Interview completed
      break;
    case "perspective:redirect":
      // Navigate to the URL provided by the embed
      window.location.href = event.data.url;
      break;
    case "perspective:close":
      // User closed the embed
      break;
    case "perspective:resize":
      // Adjust iframe height: event.data.height
      iframe.style.height = event.data.height + "px";
      break;
    case "perspective:error":
      // Handle error: event.data.error
      break;
  }
});

PostMessage Events

Event	Data	Description
perspective:ready	--	Embed loaded and ready.
perspective:submit	--	Interview completed.
perspective:redirect	{ url }	Embed wants to navigate. You must handle this.
perspective:close	--	User closed the embed.
perspective:resize	{ height }	Embed content height changed.
perspective:error	{ error }	An error occurred.

Best Practices

• Load the script once: If you have multiple embeds on the same page, include the SDK script tag only once. It discovers all trigger elements automatically.
• Use the SDK over iframes: The SDK handles responsive sizing, navigation, theming, and lifecycle events. Direct iframes require you to manage all of this yourself.
• Pass user identity via params: If your users are already authenticated, pass email and name so participants skip the identification step.
• Prefer onNavigate over default behavior: In single-page apps, handle onNavigate to use your router instead of a full page reload.