Remote Browser SDK #

Prerequisites #

In order to use this SDK you need to first create the Remote Browser instance via our Rest API. You can find instruction here..

Installation #

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

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

Usage example #

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

// 1. Get instanceURN via API call
const instanceURN = "..."; // received from the API

// 2. Create new client instance
const rbClient = remoteBrowserSdk.createClient({
  instanceURN,
  iframeSource: "rhq", // unique value per customer
  role: "...", // unique value representing a role (returned via API when creating new instance)
  userName: "Jon"
});

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

// 4. Enjoy external API to control the Remote Browser
rbClient.openInCurrentTab("https://weather.com");
rbClient.openInNewTab("https://weather.com");

Options #

When creating a new client there are several properties which are required. Additionally, there are optional properties that can be used to customize the experience.

const rbClient = remoteBrowserSdk.createClient(options);

Here's the list of available options:

• instanceURN (Required)
  Unique URN for the instance (received from the API when creating a new instance).

• iframeSource (Required)
  Unique value per customer that allows you to render our app inside yours. You will receive it from us alongside the Bearer Token.

• 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.

• logoUrl (Default: "")
  Customize the experience by using your own logo instead of the default one.

• targetOrigin (Default: "https://rooms.remotehq.com")
  If we set up a custom domain for you, it is imperative that you change this value so the SDK can securely send messages to the target origin.

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

Methods #

Using SDK can not only simplify embedding the instance on your website. It also allows you to control it with ease.

Here's the list of available methods:

• attach - Attaches the initiated instance to a DOM element

rbClient.attach("#remote-browser-container");

// you can also pass DOM Element directly
const rbContainer = document.querySelector('#remote-browser-container');
rbClient.attach(rbContainer);

• destroy - Removes the iframe and all listeners

rbClient.destroy()

• openInCurrentTab - Opens provided URL in the currently focused tab

rbClient.openInCurrentTab("https://weather.com");

• openInNewTab - Opens provided URL in a new tab

rbClient.openInNewTab("https://weather.com");

• startRecording - Starts recording the current Remote Browser. Audio is not included.

rbClient.startRecording();

• stopRecording - Stops the currently running Remote Browser recording

rbClient.stopRecording();

• on/off - Allows to listen for particular events coming from the Remote Browser

function onSomeEvent(data) { ... }

// "on()" adds listener
rbClient.on('<eventName>', onSomeEvent);

// "off()" removes listener
rbClient.off('<eventName>', onSomeEvent);

You can find list of all events in the section below.

Events #

This section describes different events that can be emitted by the Remote Browser client.

openInCurrentTab:error #

The event listener will receive string or Error.

rbClient.on("openInCurrentTab:error", (error) => {
  console.log("An error has occured: ", error);
})

openInNewTab:error #

The event listener will receive string or Error.

rbClient.on("openInNewTab:error", (error) => {
  console.log("An error has occured: ", error);
})

startRecording:error #

The event listener will receive string or Error.

rbClient.on("startRecording:error", (error) => {
  console.log("An error has occured: ", error);
})

stopRecording:error #

The event listener will receive string or Error.

rbClient.on("stopRecording:error", (error) => {
  console.log("An error has occured: ", error);
})