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: 8px;"
></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 border-radius gives the embed rounded corners to blend in with modern designs.

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.

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: '8px' }}
    />
  );
}

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: 8px;"
  ></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
• Customizing Branding — make the embed match your site's look and feel