Skip to main content

Eyeson IFrame API

The Eyeson IFrame API provides a streamlined solution for integrating video conferencing capabilities into web applications. This documentation explains how to embed fully-featured video meetings into your website or application with minimal integration effort using standard HTML and JavaScript.

The Eyeson iFrame API embeds Eyeson's default UI of an existing meeting room.

tip

The biggest advantage of Eyeson iFrame API is the correct iframe permission policy handling. This removes the permission handling and integration problems.

Permissions for IFrame API
<iframe
  src="https://app.eyeson.team/?guest=Z7pbHLtjaRauoXEoZXNNqCZR"
  allow="camera; microphone; fullscreen; speaker-selection; display-capture; picture-in-picture; web-share; autoplay; hid; clipboard-write; geolocation; compute-pressure"
></iframe>

If you plan to implement the iframe yourself make sure to set the src link to the values you get for links.gui or links.guest_join when starting the meeting.

Basic or advanced usage​

The Eyeson IFrame API can be integrated into your application in two different ways:

  • Basic Mode: A straightforward integration that embeds the Eyeson UI into your website with minimal setup. This mode requires only a container element and valid authentication.

  • Advanced Mode: Provides full programmatic control over the meeting experience, allowing you to interact with the Eyeson UI through methods like present(), chat(), and snapshot(). This mode also enables you to listen for meeting events such as user join and leave, giving you greater flexibility to customize the user experience.

Basic Mode​

Basic Setup Requirements​

To implement the Eyeson IFrame API in basic mode, you'll need:

  1. A container element in your HTML to host the Eyeson UI
  2. A valid ACCESS_KEY or guest token for authentication

Start by including the IFrame API script in your website using one of the following methods:

<script src="https://app.eyeson.team/iframe-api.js"></script>

or as Javascript ES module.

import EyesonIframe from "https://app.eyeson.team/iframe-api-esm.js";

Embed Eyeson meeting in your website​

After configuring your project to use the Eyeson IFrame API, you can embed a meeting into your website with just a few lines of code. The following examples show how to initialize a meeting using either a user-specific ACCESS_KEY or a GUEST_TOKEN:

The default usage is to register a user and get a specific access key for this user.

<html>
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- The <iframe> will be inside this <div> tag -->
    <div id="meeting"></div>

    <!-- This <script> loads the Eyeson IFrame API code -->
    <script src="https://app.eyeson.team/iframe-api.js"></script>
    <script>
      async function start() {
        // Load the user's access key for your application
        const accessKey = await fetch(
          "https://myapp.example/get-user-access-key",
        );
        // This function creates the <iframe> with the Eyeson default UI
        const meeting = new EyesonIframe("#meeting", { accessKey });
        meeting.on("error", (error) => {
          // Example error notification
          console.error(error);
          // Remove the <iframe> and clear the meeting instance
          meeting.close();
        });
      }

      start();
    </script>
  </body>
</html>

Advanced Mode​

To enable advanced features, register your website's origin when creating the meeting. This unlocks additional capabilities and provides programmatic control over the meeting interface.

Authenticate your website​

note

Authentication is optional. IFrame API will work in basic mode without authentication.

In advanced mode, methods to interact with the Eyeson UI inside the iframe are available, like present, chat, snapshot.

To enable advanced mode, in the meeting start command you need to set the options[custom_fields][iframe_postmessage_origin] parameter to the correct website origin, for example

options[custom_fields][iframe_postmessage_origin]=https://app.myawesomeapp.com

Embed Eyeson meeting in your website​

<html>
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- The <iframe> will be inside this <div> tag -->
    <div id="meeting"></div>

    <!-- This <script> loads the Eyeson IFrame API code -->
    <script src="https://app.eyeson.team/iframe-api.js"></script>
    <script>
      // EyesonIframe instance reference
      let meeting = null;

      async function start() {
        // Load the user's access key for your application
        const accessKey = await fetch(
          "https://myapp.example/get-user-access-key",
        );
        // This function creates the <iframe> with the Eyeson default UI
        meeting = new EyesonIframe("#meeting", {
          accessKey,
          events: {
            onReady,
            onError,
            onMeetingJoin,
            onMeetingLeave,
            onMeetingError,
          },
        });
      }

      async function presentPdf() {
        try {
          // Load pdf file as blob
          const pdf = await fetch("https://myapp.example/get-pdf");
          // Start presentation in Eyeson UI
          await meeting.present(pdf);
        } catch (error) {
          showError("Present PDF failed");
        }
      }

      async function sendChat(message) {
        try {
          // Send a chat message in Eyeson UI
          await meeting.chat(message);
        } catch (error) {
          showError("Send chat failed");
        }
      }

      async function createSnapshot() {
        try {
          // Create a snapshot
          await meeting.snapshot();
        } catch (error) {
          showError("Create snapshot failed");
        }
      }

      function onReady() {
        // Eyeson UI is loaded and ready
      }

      function onError(error) {
        // Eyeson UI could not be loaded
        console.error(error);
        meeting.close();
      }

      function onMeetingJoin() {
        // User has joined the meeting (after preview screen)
      }

      function onMeetingLeave(reason) {
        // User has left the meeting (by intention or error)
      }

      function onMeetingError(reason) {
        // User is not able to join the meeting at all
      }

      start();
    </script>
  </body>
</html>

Embed in your website using the ES Module​

The IFrame API is also available as an ES module, which allows for more modern JavaScript import syntax and better compatibility with contemporary web frameworks and build systems.

import EyesonIframe from "https://app.eyeson.team/iframe-api-esm.js";

async function start() {
  const accessKey = await fetch("https://myapp.example/get-user-access-key");
  const meeting = new EyesonIframe("#meeting", { accessKey });
  meeting.on("error", (error) => {
    console.error(error);
    meeting.close();
  });
}

start();

The Eyeson IFrame API is fully compatible with the Permalink API, allowing you to seamlessly embed persistent meeting rooms created through the permalink functionality into your web applications.

Simply set options isPermalink=true and use the accessKey or guest.token fields.

import EyesonIframe from "https://app.eyeson.team/iframe-api-esm.js";

async function start() {
  const permalinkGuestToken = "HoYq1gudkP9D7NXF6ERTnd05";
  const meeting = new EyesonIframe("#meeting", {
    isPermalink: true,
    guest: { token: permalinkGuestToken },
  });
  // ...
}

start();