Using the Embed Widget

The Koji embed widget lets you place an interview directly on your website so participants never have to leave the page. It works as a standard iframe and takes just a couple of minutes to set up.

When to Use the Embed Widget

Embedding is a great fit when you want to:

• Collect feedback on a product page, pricing page, or help center article
• Run a post-purchase interview on a thank-you or confirmation page
• Integrate an interview into an existing web application or dashboard
• Keep participants in your own branded environment

If you prefer to send participants to a dedicated interview page instead, see Sharing Your Interview Link.

Getting the Embed Code

1. Open your project and navigate to the Integrate tab.
2. You will see the Embed Code Generator, which provides ready-to-copy code snippets.
3. Choose your configuration options (theme, dimensions) and copy the code.

The generator provides three code formats:

• Basic iframe — the simplest option, just paste and go
• iframe with events — includes a JavaScript listener for interview lifecycle events
• React component — a ready-made React wrapper for Next.js, Create React App, or similar frameworks

Basic Iframe

The simplest embed is a standard HTML iframe:

<iframe
  src="https://yourdomain.com/embed/YOUR_PROJECT_ID"
  width="100%"
  height="700px"
  frameborder="0"
  allow="microphone"
  style="border: none; border-radius: 12px;"
></iframe>

Paste this into any HTML page, CMS block, or template. The interview will render inside the frame and handle the full participant flow — landing page, mode selection, intake form, conversation, and completion.

Key Attributes

• allow="microphone" — required if you want participants to use voice mode. Without this attribute, the browser will block microphone access inside the iframe.
• width and height — adjust to fit your page layout. A height of 700 pixels works well for most setups.
• style — the default border-radius of 12px gives the embed rounded corners to blend in with modern designs. Adjust this value to match your site's design language.

Configuration Options

Theme

By default, the embed uses the dark theme. You can switch to light mode by adding a query parameter:

https://yourdomain.com/embed/YOUR_PROJECT_ID?theme=light

Choose the theme that matches your website's design.

API Key

If you want to track embed usage or enforce origin restrictions, you can pass an API key:

https://yourdomain.com/embed/YOUR_PROJECT_ID?api_key=YOUR_KEY

This is optional for basic embeds but recommended if you are embedding on a production site.

External ID

To associate embedded interviews with users in your own system, pass an external identifier:

https://yourdomain.com/embed/YOUR_PROJECT_ID?external_id=user_abc123

The external_id is attached to the respondent record and can be used to match interview data back to your internal user database. You can combine multiple parameters:

https://yourdomain.com/embed/YOUR_PROJECT_ID?theme=light&api_key=YOUR_KEY&external_id=user_abc123

Structured Questions in Embeds

If your study includes structured questions such as scales, multiple choice, ranking, or yes/no questions, the interactive question widgets render fully within the embed. Participants can interact with sliders, select options, and drag to rank items just as they would on the standalone interview page.

Listening for Events

The embed communicates with your parent page through the browser's postMessage API. This lets you react to interview milestones — for example, showing a custom thank-you message or redirecting the user after completion.

Add a message listener to your page:

window.addEventListener('message', function(event) {
  // Always verify the origin for security
  if (event.origin !== 'https://yourdomain.com') return;

  switch(event.data.type) {
    case 'koji:ready':
      // The interview has loaded and is ready
      break;
    case 'koji:interview_started':
      // The participant has begun the conversation
      break;
    case 'koji:interview_completed':
      // The interview is finished — event.data.result has details
      break;
  }
});

Available Events

Use the koji:interview_completed event to trigger your own follow-up actions, such as showing a discount code, redirecting to another page, or logging the completion in your analytics.

React Integration

If your site uses React, the embed code generator provides a ready-made component:

function KojiInterview({ onComplete }) {
  const iframeRef = useRef(null);

  useEffect(() => {
    function handleMessage(event) {
      if (event.origin !== 'https://yourdomain.com') return;
      if (event.data.type === 'koji:interview_completed') {
        onComplete?.(event.data.result);
      }
    }
    window.addEventListener('message', handleMessage);
    return () => window.removeEventListener('message', handleMessage);
  }, [onComplete]);

  return (
    <iframe
      ref={iframeRef}
      src="https://yourdomain.com/embed/YOUR_PROJECT_ID"
      width="100%"
      height="700px"
      frameBorder="0"
      allow="microphone"
      style={{ border: 'none', borderRadius: '12px' }}
    />
  );
}

Drop this into your React app and pass an onComplete callback to handle interview completion.

Responsive Sizing

For responsive layouts, wrap the iframe in a container and use CSS to control its dimensions:

<div style="width: 100%; max-width: 800px; margin: 0 auto;">
  <iframe
    src="https://yourdomain.com/embed/YOUR_PROJECT_ID"
    width="100%"
    height="700px"
    frameborder="0"
    allow="microphone"
    style="border: none; border-radius: 12px;"
  ></iframe>
</div>

On mobile, the embed adjusts its internal layout automatically. A minimum width of 320 pixels is recommended.

Security Considerations

• Origin verification: Always check event.origin in your message listener to prevent cross-origin attacks.
• API key restrictions: If you use an API key, configure allowed origins in your project settings so only your domain can load the embed.
• HTTPS required: The embed must be loaded over HTTPS to enable microphone access for voice interviews.

Troubleshooting

• Microphone not working in embed: Make sure the allow="microphone" attribute is present on the iframe tag. The parent page must also be served over HTTPS.
• Embed not loading: Verify the project ID in the URL is correct and that the study is published.
• Events not firing: Confirm you are checking the correct origin in your event listener.

Next Steps

• Sharing Your Interview Link — alternative distribution methods
• Headless API Overview — start interviews programmatically from your backend
• Customizing Branding — make the embed match your site's look and feel
• Structured Questions Guide — add interactive question types to your study