Reference

Initializing the SDK

Hyperbeam(container, embedURL, options?): Promise<HyperbeamClient> Use Hyperbeam(container, embedURL, options?) to create an instance of the HyperbeamClient object. The HyperbeamClient object is your entrypoint to the rest of the Hyperbeam JavaScript SDK.

JavaScript

import Hyperbeam from "@hyperbeam/web"
...
const hb = await Hyperbeam(container, embedURL, options)

Method Parameters

HTMLDivElement | HTMLIFrameElement

The container can be either a div or an iframe element, though it is highly advised to use a div.

string

The embedURL is retrieved from the REST API.

HyperbeamOptions Object

Initialization options. All properties are optional.

Show child attributes

string

An admin token returned from the REST API that will grant this user access to managing user permissions and programmatic navigation.

number

default:"2000"

Number of milliseconds until the request to the virtual browser times out. If the request times out, the returned promise will be rejected.

number

default:"1.0"

Starting volume of the virtual browser.

boolean

default:"false"

Starting video pause state of the virtual browser.

boolean

default:"false"

Starting playout delay state of the virtual browser. When playoutDelay = true, input lag increases but smoothness is improved and frame drops are reduced.

boolean

default:"true"

Delegate global keyboard events to the embed.

JSONValue

Data to be provided to your webhook endpoint if you’re using webhook authentication.

(frame: ImageBitmap | HTMLVideoElement) => void

Callback called with the virtual computer’s video frame data. For Chromium-based browsers, its type is ImageBitmap. For other browsers, it’s an HTMLVideoElement. Most frameworks like Three.js and Babylon.js can handle both types automatically.

(track: MediaStreamTrack) => void

Callback called with a MediaStreamTrack of the virtual computer’s audio stream.

(e: PeerMouseEvent) => void

Callback called when another user moves their mouse cursor on top of the virtual browser. Useful for implementing multiplayer cursors.

(e: DisconnectEvent) => void

Callback called when the user disconnects from the virtual browser. e.type is an enum with one of the following values: "request" -> virtual browser was manually shut down. "inactive" -> inactive timeout was triggered. "absolute" -> absolute timeout was triggered. "kick" -> user was kicked from the session.

(e: CloseWarningEvent) => void

Callback called when a timeout either surpasses the warning threshold, or has been reset and is no longer passed the warning threshold. e.type is an enum that refers to the timeout’s type tied to the event. Possible values are "inactive" and "absolute". e.deadline = null | { delay: number, closeDate: string }. If e.deadline is null, then the timeout was reset and is no longer passed the warning threshold. If e.deadline is set, e.deadline.delay is the number of milliseconds until the timeout is triggered, and e.deadline.closeDate is an RFC3339 formatted string of when the timeout will occur.

(e: ConnectionStateEvent) => void

Callback called when the connection state of the video stream has changed. e.state = "connecting" | "playing" | "reconnecting". You can use this to show custom reconnecting UI, and detecting if a user has a sub-optimal connection to the virtual browser.

See initialization example.

The HyperbeamClient object

The HyperbeamClient object allows you to programmatically control the virtual browser, set user permissions, and debug connection issues among other things.

JavaScript

const hb: Promise<HyperbeamClient> = await Hyperbeam(
  container,
  embedURL,
  options
);

Properties

string

The client’s user ID. See example.

string

The client’s admin token. See example.

number

The local volume of the virtual browser. See example.

number

The width of the virtual browser in pixels. See example.

number

The height of the virtual browser in pixels. See example.

number

The maximum virtual browser area that can be allocated in pixels. See example.

boolean

Pauses the video stream of the virtual browser locally. See example.

boolean

When playoutDelay = true, input lag increases but smoothness is improved and frame drops are reduced.

Tabs Object

The virtual browser Tabs object. See example.

Methods

reconnect

hb.reconnect(): void Useful in situations where you need to troubleshoot the browser disconnecting. See example.

destroy

hb.destroy(): void Tears down network connections and browser events. Always call this before removing the container element from the page. See example.

addRoles

hb.addRoles(userIds, roles, exclusive): Promise<void> Adds the list of roles to all the provided user ids. Method parameters

string[]

required

List of user ids

string[]

required

List of roles to be assigned to the provided user ids

bool

default:false

If set to true, the roles are assigned to all users except the provided list of user ids.

removeRoles

Removes the list of roles from all the provided user ids. hb.removeRoles(userIds, roles, exclusive): Promise<void> Sets the permission of a user by their ID. The client must have an admin token set to manage user permissions. See example. Method parameters

string[]

required

List of user ids

string[]

required

List of roles to be removed from the provided user ids

bool

default:false

If set to true, the roles are removed from all users except the provided list of user ids.

setPermissions

hb.setPermissions(userId, permissionData): Promise<void>

setPermissions is deprecated, please use addRoles and removeRoles

Sets the permission of a user by their ID. The client must have an admin token set to manage user permissions. See example. Method parameters

string

The user ID to set permissions for.

object

All keys can be omitted: if the key is omitted, then the existing value will be unchanged.

Show child attributes

number

default:"0"

Higher value = higher priority. Users with a higher priority will preempt the control of lower priority users.

number

Number of milliseconds until a user is considered “idle”. Once a user is considered idle, they no longer preempt lower priority users until they interact with the virtual browser again.

boolean

default:"<control_disable_default>"

If control_disabled = true, all control input (mouse movements, keyboard presses) will be ignored. Note that disabling control does not restrict access to any APIs that require admin tokens.

sendEvent

hb.sendEvent(event): void Sends a keyboard, mouse, or mouse wheel event to the Hyperbeam browser. See example. Method parameters

KeyEvent | MouseEvent | WheelEvent

resize

hb.resize(width, height): void Resizes the virtual browser to the specified width and height, in pixels. The arguments must meet the following conditions, otherwise the function will throw a RangeError: width * height cannot be greater than hb.maxArea. hb.maxArea is the maximum area that can be allocated in pixels. See example. Method parameters

number

The width of the virtual browser in pixels.

number

The height of the virtual browser in pixels.

ping

hb.ping(): void Resets the inactive timeout. Useful for situations where the user is not interacting with the Hyperbeam browser, but is performing actions on other parts of your application.

getRegionInfo

getRegionInfo(): Promise<HyperbeamRegionInfo> The Hyperbeam Web SDK provides a function called getRegionInfo() that returns a HyperbeamRegionInfo object. This object refers to the optimal region to spin up a virtual computer based on the client’s location.

JavaScript

import {getRegionInfo} from "@hyperbeam/web"
...
const regionInfo = await getRegionInfo()

How to use getRegionInfo to optimize server location.

HyperbeamRegionInfo

Properties

string

Two-letter region code.

string

Country code.

Home

Guides

REST API

Client SDKs

Initializing the SDK

Method Parameters

The HyperbeamClient object

Properties

Methods

reconnect

destroy

addRoles

removeRoles

setPermissions

sendEvent

resize

ping

getRegionInfo

HyperbeamRegionInfo

Properties

​Initializing the SDK

​Method Parameters

​The HyperbeamClient object

​Properties

​Methods

​reconnect

​destroy

​addRoles

​removeRoles

​setPermissions

​sendEvent

​resize

​ping

​getRegionInfo

​HyperbeamRegionInfo

​Properties

Initializing the SDK

Method Parameters

The HyperbeamClient object

Properties

Methods

reconnect

destroy

addRoles

removeRoles

setPermissions

sendEvent

resize

ping

getRegionInfo

HyperbeamRegionInfo

Properties