Embed API Reference

The Perspective Embed SDK lets you drop interviews into any web page with a script tag and a data attribute. For more control, use the JavaScript API to create and manage embed instances programmatically.

For the user-facing setup guide (choosing embed types, previewing, copying snippets from the dashboard), see Embed Interviews on Your Website or App.

Quick Start#

Add the SDK script and a trigger element to your page:

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

Replace RESEARCH_ID with the ID of your perspective (visible in the dashboard URL or returned by the Create Perspective API).

The script loads asynchronously and initializes all trigger elements on the page automatically.

Embed Types#

Each embed type uses a different data attribute on the trigger element:

Button-based types (Popup, Slider) require a <button> element. The user clicks it to open the interview.

Examples#

Inline widget:

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

Popup triggered by a button:

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

Floating chat bubble:

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

URL Parameters#

Pass parameters via the data-perspective-params attribute as comma-separated key=value pairs:

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

Built-In Parameters#

Any unrecognized parameters are treated as custom key-value pairs. They are passed through to webhooks and data exports, making them useful for attribution and tracking (e.g., campaign=summer2024).

The SDK also forwards search parameters from the parent page URL into the embed iframe, except for SDK-owned parameters such as embed, embed_type, theme, and brand.* color keys. Parameters passed explicitly through data-perspective-params or the JavaScript params option override forwarded parent-page values. For more on how this becomes participant metadata, see Track Participant Context.

Theming#

Color Mode#

Force a color mode with data-perspective-theme:

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

Accepted values: dark, light, system (default, follows OS preference).

Brand Colors#

Override brand colors with data-perspective-brand (light mode) and data-perspective-brand-dark (dark mode):

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

Available color tokens:

Advanced Attributes#

Use these attributes when you need more control over SDK behavior:

Auto-Open (Popup Only)#

Trigger a popup automatically without a user click:

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

Auto-open triggers:

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

Show-once options:

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

JavaScript API#

For programmatic control, use the global Perspective object:

// Create an inline widgetconst container = document.querySelector("#perspective-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 popupconst popup = Perspective.openPopup({  researchId: "RESEARCH_ID",  onClose: () => console.log("Closed"),});
// Open a sliderconst slider = Perspective.openSlider({  researchId: "RESEARCH_ID",});
// Create a floating chat bubbleconst float = Perspective.createFloatBubble({  researchId: "RESEARCH_ID",});
// Create a full-viewport embedconst fullpage = Perspective.createFullpage({  researchId: "RESEARCH_ID",});
// Clean up without changing persisted open/closed statewidget.unmount();
// Explicitly close and persist closed state for restorable embedspopup.destroy();

All creation functions return a handle with unmount(), destroy(), and update() methods. Use unmount() for framework cleanup or route changes. Use destroy() when you intentionally want to close the embed; popup, slider, and float embeds can persist that closed state. Float handles also expose open(), close(), toggle(), and isOpen.

The browser global also exposes Perspective.mount(containerOrSelector, config) for selector-based mounting, Perspective.init(config) for non-widget embed types, Perspective.destroy(researchId), Perspective.destroyAll(), Perspective.autoInit(), Perspective.configure(config), and Perspective.getConfig().

Callbacks#

NPM JavaScript SDK#

For TypeScript or bundler-based apps that do not need React components, install @perspective-ai/sdk:

npm install @perspective-ai/sdk

import {  createWidget,  openPopup,  openSlider,  createFloatBubble,  createFullpage,  configure,  fetchEmbedConfig,} from "@perspective-ai/sdk";
configure({ host: "https://getperspective.ai" });
const container = document.querySelector<HTMLElement>("#perspective-widget");const widget = createWidget(container, {  researchId: "RESEARCH_ID",  params: { source: "app", user_id: "123" },});
const popup = openPopup({ researchId: "RESEARCH_ID" });const slider = openSlider({ researchId: "RESEARCH_ID" });const float = createFloatBubble({ researchId: "RESEARCH_ID" });const fullpage = createFullpage({ researchId: "RESEARCH_ID" });
const config = await fetchEmbedConfig("RESEARCH_ID");
widget.unmount();popup.destroy();float.open();float.close();

createWidget accepts an HTMLElement | null. If you want selector-based mounting, use the browser global Perspective.mount("#selector", config) or resolve the element before calling the NPM function.

React SDK#

For React and Next.js apps, use @perspective-ai/sdk-react instead of the script tag. It provides typed components and hooks with full lifecycle control.

Installation#

npm install @perspective-ai/sdk-react

Widget (Inline Embed)#

Renders the interview directly inside a container element:

import { Widget } from "@perspective-ai/sdk-react";
function FeedbackWidget() {  return (    <Widget      researchId="RESEARCH_ID"      params={{ source: "app", user_id: "123" }}      onReady={() => console.log("Loaded")}      onSubmit={() => console.log("Completed")}    />  );}

The Widget component accepts all standard div props (className, style, etc.) for sizing and layout.

Popup#

Use the usePopup hook for modal overlays:

import { usePopup } from "@perspective-ai/sdk-react";
function FeedbackButton() {  const { open, isOpen } = usePopup({    researchId: "RESEARCH_ID",    onSubmit: () => console.log("Completed"),  });
  return <button onClick={open}>Give Feedback</button>;}

Slider#

Use the useSlider hook for a side panel that slides in from the edge:

import { useSlider } from "@perspective-ai/sdk-react";
function SliderTrigger() {  const { open } = useSlider({ researchId: "RESEARCH_ID" });  return <button onClick={open}>Open Survey</button>;}

Float Bubble#

A floating chat bubble anchored to the corner of the page:

import { FloatBubble } from "@perspective-ai/sdk-react";
function App() {  return <FloatBubble researchId="RESEARCH_ID" onSubmit={handleSubmit} />;}

Fullpage#

Takes over the entire viewport:

import { Fullpage } from "@perspective-ai/sdk-react";
function InterviewPage() {  return <Fullpage researchId="RESEARCH_ID" />;}

Auto-Open#

Trigger a popup automatically after a delay or on exit intent:

import { useAutoOpen } from "@perspective-ai/sdk-react";
function AutoSurvey() {  useAutoOpen({    researchId: "RESEARCH_ID",    trigger: { type: "timeout", delay: 5000 },    showOnce: "session",  });  return null;}

React Callbacks#

All components and hooks accept the same callback props as the JavaScript API: onReady, onSubmit, onNavigate, onClose, and onError. See the Callbacks table above for details.

React helpers also include useFloatBubble, useEmbedConfig, useThemeSync, and DiscoveryMetadata for headless float control, config fetching, theme synchronization, and server-rendered discovery metadata.

Direct Iframe Embed#

If you cannot use the SDK (e.g., in environments that restrict third-party scripts), embed the interview directly in an iframe:

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

When using a direct iframe, you must add a postMessage listener to handle navigation and lifecycle events:

var iframe = document.getElementById("perspective-iframe");var allowedOrigin = new URL(iframe.src).origin;
window.addEventListener("message", (event) => {  if (event.origin !== allowedOrigin) return;  if (event.source !== iframe.contentWindow) 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#

Add allow="microphone" to the iframe if the interview uses voice mode.

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.