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.

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.