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

container

HTMLDivElement | HTMLIFrameElement

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

embedURL

string

The embedURL is retrieved from the REST API.

options

HyperbeamOptions Object

Initialization options. All properties are optional.

adminToken

string

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

timeout

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.

volume

number

default: "1.0"

Starting volume of the virtual browser.

videoPaused

boolean

default: "false"

Starting video pause state of the virtual browser.

hb.playoutDelay

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.

delegateKeyboard

boolean

default: "true"

Delegate global keyboard events to the embed.

webhookUserdata

JSONValue

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

frameCb

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

audioTrackCb

(track: MediaStreamTrack) => void

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

onCursor

(e: PeerMouseEvent) => void

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

onDisconnect

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

onCloseWarning

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

onConnectionStateChange

(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

hb.userId

string

The client’s user ID. See example.

hb.adminToken

string

The client’s admin token. See example.

hb.volume

number

The local volume of the virtual browser. See example.

hb.width

number

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

hb.height

number

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

hb.maxArea

number

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

hb.videoPaused

boolean

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

hb.playoutDelay

boolean

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

hb.tabs

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.

setPermissions

hb.setPermissions(userId, permissionData): 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

userId

string

The user ID to set permissions for.

permissionData

object

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

sendEvent

hb.sendEvent(event): void

Sends a keyboard, mouse, or mouse wheel event to the Hyperbeam browser. See example.

Method parameters

event

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

width

number

The width of the virtual browser in pixels.

height

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

region

string

Two-letter region code.

country

string

Country code.

Home

Guides

REST API

Client SDKs

Initializing the SDK

Method Parameters

The HyperbeamClient object

Properties

Methods

reconnect

destroy

setPermissions

sendEvent

resize

ping

getRegionInfo

HyperbeamRegionInfo

Properties

Home

Guides

REST API

Client SDKs

​Initializing the SDK

​Method Parameters

​The HyperbeamClient object

​Properties

​Methods

​reconnect

​destroy

​setPermissions

​sendEvent

​resize

​ping

​getRegionInfo

​HyperbeamRegionInfo

​Properties

Initializing the SDK

Method Parameters

The HyperbeamClient object

Properties

Methods

reconnect

destroy

setPermissions

sendEvent

resize

ping

getRegionInfo

HyperbeamRegionInfo

Properties