Creating a Live View

What is a Live View?

A live view is a way to provide real-time interactive access of your browser to your users. You can use a live view to support a range of use cases, including:

• Authentication workflows
• Human / AI training use cases
• Human in the loop workflows

How to use a Live View

1

Step 1

Once you have a session and have loaded a url in a window, you can request a live view URL from the API.

NodeJSPython

1
const windowInfo = await client.windows.getWindowInfo(session.data.id, windowId);
2
const liveViewUrl = windowInfo.data.liveViewUrl;

If you’re using Puppeteer, Playwright, or Selenium, you can use framework specific getWindowInfo variants.

NodeJSPython

1
const windowInfo = await client.windows.getWindowInfoForPuppeteerPage(session.data, page); // page is a puppeteer.Page object
2
const windowInfo = await client.windows.getWindowInfoForPlaywrightPage(session.data, page); // page is a playwright.Page object
3
const windowInfo = await client.windows.getWindowInfoForSeleniumDriver(session.data, driver); // driver is a seleniumWebdriver.WebDriver object

2

Step 2

You may load the live view URL in your browser, or more likely, embed it in your application as an iframe.

1
<iframe
2
  allow="clipboard-read;clipboard-write"
3
  title="<YOUR_BROWSER_ID>" // iframe elements require a unique title property
4
  id="<YOUR_BROWSER_ID>" // used to identify the iframe in live view message events
5
  src="<YOUR_LIVE_VIEW_URL>"
6
/>

Here’s an example of what an embedded live view might look like in an application:

3

Step 3

You can optionally set up the live view to include a navigation bar, which will provide a URL bar and other controls to the user.

NodeJSPython

1
const windowInfo = await client.windows.getWindowInfo(session.data.id, windowId, {
2
  includeNavigationBar: true,
3
});
4
const liveViewUrl = windowInfo.data.liveViewUrl;

4

Step 4

If you would like to receive messages from the Live View, you can set up a message listener in your application to let you know when certain events occur, such as when the page url changes. Check out the section below on Messages for more information.

Controlling the Live View’s dimensions

By default, the live view will resize to fit the wrapping iframe or window. You can control the Live View’s size by simply adjusting the iframe’s dimensions and the browser contents will resize to fit. However, you may also choose to set the screen resolution and disable resizing as shown below.

1
const windowInfo = await client.windows.getWindowInfo(session.data.id, windowId, {
2
  includeNavigationBar: true,
3
  screenResolution: "1920x1080", // Width x Height
4
  disableResize: true,
5
});

Messages

The Live View iframe and parent window can communicate with each other via the window.postMessage API. Each message has an eventName field that indicates the type of event, and some messages have a payload field containing relevant data.

To send and receive live view messages, you will first need to install the Airtop SDK for your frontend JS/TS app.

$
npm install @airtop/sdk

Message handling in the parent window

You can set up a message listener in your application to handle messages from the Live View as shown below.

1
import { LiveViewEventName, LiveViewMessage } from "@airtop/sdk";
2
3
window.addEventListener('message', function (event) {
4
  const iframe = document.getElementById('airtopLiveView');
5
  if (!iframe || event.source !== iframe.contentWindow) {
6
    // Message did not originate from the live view iframe
7
    return;
8
  }
9
10
  const message: LiveViewMessage = event.data;
11
12
  switch (message.eventName) {
13
    case LiveViewEventName.UrlChange: {
14
      handleUrlChange(message.payload); // Message payload is the new url
15
      break;
16
    }
17
    default: {
18
      return;
19
    }
20
  }
21
});

Whenever a relevant event occurs in the live view, the live view iframe will send a message to the parent window, which you can handle as appropriate for your use case.

Sending messages to the live view

If you need your frontend application to send messages to the live view, you can use the postMessage API as shown below. Typically, if you use the built in navigation bar, you won’t need to send messages to the live view, but if you have a custom navigation bar, you may need to use this mechanism to control the live view. Of course, your backend service can always control the browser and any changes will be reflected in the live view for your end users.

1
import { LiveViewEventName, LiveViewMessage } from "@airtop/sdk";
2
3
const sendMessageToBrowser = (eventName: string, payload?: any) => {
4
  const message: LiveViewMessage = {
5
    eventName,
6
    ...(payload && { payload }),
7
  };
8
9
  const iframe = document.getElementById(browserId) as HTMLIFrameElement;
10
11
  if (!iframe) {
12
    return;
13
  }
14
15
  iframe.contentWindow.postMessage(message, 'https://live.airtop.ai');
16
};