Return to top
On this page

Embedding the Remote Browser

Prerequisites

In order to start creating and embedding Remote Browsers on your website, you need to have a BEARER token generated. Check out REST API overview to get started.

Create Remote Browser (Backend)

Use our REST API to create new instance, for example:

javascript
async function createRemoteBrowser() {
  const response = await fetch("https://api.remotehq.com/v1/embed/remote-browser", {
    method: "POST",
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${TOKEN}`
    },
    body: JSON.stringify({
      browserURL: "https://google.com",
        region: "us-east-1",
        resolution: "medium"
    })
  });
  return response.json();
}

WARNING

Make sure you do not expose the Bearer token to your users. Use it only in your backend API service. Your application frontend should never call api.remotehq.com directly. Always use your backend API service proxy.

  • Learn more about the configuration options here.
  • Check out API samples in other languages here.

Example response:

json
{
  "data": {
    "roles": {
      "owner": "e310sk1ll920...",
      "guest": "i1o1831kczmo..."
    },
    "instanceURN": "us-east-1__e862427b...",
    "embedURL": "https://rooms.remotehq.com/embed/remote-browser/us-east-1__e862427b...",
    "state": "RUNNING",
    "isPersisted": false,
    "features": []
  },
  "error": null
}

TIP

Once you have an instance created, you can play with your Remote Browser here: https://playground.remotehq.com

WARNING

In order to test interactions between multiple users on a single computer you must either use incognito mode or different browser for each user. This is due to the fact that we support a single unique user per browser.

Install the SDK

bash
# Install via npm
npm install --save @remotehq/remote-browser-sdk

# or via yarn
yarn add @remotehq/remote-browser-sdk

Create new client and attach to DOM

js
import * as remoteBrowserSdk from "@remotehq/remote-browser-sdk";

const instanceURN = "..."; // received from the API

const rbClient = remoteBrowserSdk.createClient({
  instanceURN,
  iframeSource: "rhq",
  role: "e310sk1ll920...", // received from the API. Use appropriate value for the intented role.
  userName: "Jon"
});

rbClient.attach("#remote-browser-container"); // Selector or Element

Learn more about the SDK features and configuration options here.

Embed manually

In addition to the instanceURN, the API also returns an embedURL. The embedURL can be used as the src attribute on an iframe element.

For example:

html
<iframe src="https://rooms.remotehq.com/embed/remote-browser/uniqueInstanceURN?userName=Louis" allowfullscreen allow="autoplay; fullscreen" />

INFO

If you want to customize the Remote Browser you will need to use query params and construct the final URL yourself.

WARNING

In order to allow audio to play automatically make sure the allow property has autoplay value set as per the example above. Also, if you want the fullscreen feature to work it needs to be allowed via element properties too.

Available query params:

  • userName (Default: Guest)
    Name of the user connecting to the Remote Browser. Default is 'Guest'. This is used for cursor annotations.

  • role (Default: -)
    Unique value representing an intended role (received from the API when creating a new instance).

  • allowFullscreen (Default: false)
    Whether you want the user to have an option to make the Remote Browser occupy their entire screen or not.

  • disableAudio (Default: false)
    Disables the ability to hear audio from the Remote Browser.

  • barLocation (Default: top-right)
    Determines location of the Remote Browser navigation bar. Available options: top-right, top-left

Copyright © 2022 by RemoteHQ