Embed RevealAI iFrame

Written By revealai

Last updated 3 days ago

iFraming your interview is optional, but if you'd like to embed it in another website or application, you can configure the iFrame settings. Once your interview is ready for testing, click the iFrame button (screenshot below) at the top of the Design tab. This will open up an iframe configuration widget that will help you create some iframe HTML code. This window is not a settings window, it is just for copying out some HTML code.

  • Reveal Tracking ID (rtid): Attach a unique ID to an interview so it can be matched with external data. rtid=RTIDGOESHERE

  • Interview Theme: Set to the participant's system default, light mode, or dark mode. Defaults to system default. colorMode=light/dark

  • Show Progress Bar: Display participant progress at the top of the interview. showProgress=true

  • Show Splash: Show the chatbot's description splash screen. showSplash=true

  • Show Title: Show the chatbot's title. showTitle=true

Here's example iFrame code with everything enabled:

Example
<iframe src="https://interview.dev.getreveal.ai/i/revealai-demo?rtid=RTIDGOESHERE&showProgress=true&showSplash=true&showTitle=true&colorMode=dark" />

Sizing

Iframes accept a width and height parameter to size them. We recommend that the height is at least 550px to prevent strange overflows and scrolling behavior

Attaching a tracking ID with rtid

To attach a tracking ID, use the rtid query parameter: https://interview.getreveal.ai/i/revealai-demo?rtid=ABC123 (where ABC123 is your tracking ID). This is typically used when embedding an interview to match responses with your external system IDs. These tracking IDs will appear in your Reveal dashboard and data exports.

Testing your tracking ID:

  1. Complete an interview in preview mode with your rtid parameter

  2. Go to the Collect Dashboard and turn on "Show Preview Interviews"

  3. Scroll to the "Transcripts" section to find your test interview

  4. Verify the Tracking ID appears correctly

If the tracking ID doesn't appear or looks incorrect, contact the RevealAI team.

For details about using a tracking ID to integrate with another survey platform see Integrating Reveal AI Into Other Survey Platforms

Communicating with the iFrame

When embedded in an iframe, the interview client emits these postMessage events. More than one event can be emitted, for example if the screener completes and the decision is to terminate the interview, the client will emit both reveal-ai-emit-end-interview and reveal-ai-emit-ai-detection

Code in the parent page like this can be used to listen/react to events

Example
window.addEventListener("message", (event) => {
  if (event.data.type === "reveal-ai-emit-end-interview") {
    // do whatever you need to do 
    const id = event.data.data.id
  }
});

Iframe Events

Here are the events that are emitted by the interview

// Emitted when the ai screener finishes
{
  type: "reveal-ai-emit-ai-detection";
  data: {
    /** the Reveal ID of the interview */
    id: string;
    /** tracking ID (if used in interview) */
    rtid?: string;
    action: "continue" | "redirect" | "terminate";
    result: "pass" | "fail";
    /** detected likelihood of AI. "High" means result=fail, "Low" and "Medium" means result=pass */
    label: "Low" | "Medium" | "High";
  };
};

// emitted ANYTIME the interview terminates
{
  type: "reveal-ai-emit-end-interview";
  data: {
    /** the Reveal ID of the interview */
    id: string;
    /** tracking ID (if used in interview) */
    rtid?: string;
    /** DEPRECATED: use `id` instead */
    session_id: string;
  };
};

// emitted ANYTIME the interview will be redirected
{
  type: "reveal-ai-emit-redirect";
  data: {
    /** the Reveal ID of the interview */
    id: string;
    /** tracking ID (if used in interview) */
    rtid?: string;
    /** the URL that the respondent should be redirected to */
    url: string;
  };
};