> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperbeam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

## Initializing the SDK

`Hyperbeam(container, embedURL, options?): Promise<HyperbeamClient>`

Use `Hyperbeam(container, embedURL, options?)` to create an instance of the [HyperbeamClient](/client-sdk/javascript/reference#the-hyperbeamclient-object) object. The HyperbeamClient object is your entrypoint to the rest of the Hyperbeam JavaScript SDK.

```js JavaScript theme={null}
import Hyperbeam from "@hyperbeam/web"
...
const hb = await Hyperbeam(container, embedURL, options)
```

### Method Parameters

<br />

<ParamField body="container" type="HTMLDivElement | HTMLIFrameElement">
  The container can be either a `div` or an `iframe` element, though it is
  highly advised to use a `div`.
</ParamField>

<ParamField body="embedURL" type="string">
  The embedURL is retrieved from the [REST API](/rest-api).
</ParamField>

<ParamField body="options" optional type="HyperbeamOptions Object">
  Initialization options. All properties are optional.

  <Expandable>
    <ParamField body="adminToken" type="string">
      An admin token returned from the REST API that will grant this user access to managing user permissions and programmatic navigation.
    </ParamField>

    <ParamField body="timeout" type="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.
    </ParamField>

    <ParamField body="volume" type="number" default="1.0">
      Starting volume of the virtual browser.
    </ParamField>

    <ParamField body="videoPaused" type="boolean" default="false">
      Starting video pause state of the virtual browser.
    </ParamField>

    <ParamField body="hb.playoutDelay" type="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.
    </ParamField>

    <ParamField body="delegateKeyboard" type="boolean" default="true">
      Delegate global keyboard events to the embed.
    </ParamField>

    <ParamField body="webhookUserdata" type="JSONValue">
      Data to be provided to your webhook endpoint if you're using webhook authentication.
    </ParamField>

    <ParamField body="frameCb" type="(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.
    </ParamField>

    <ParamField body="audioTrackCb" type="(track: MediaStreamTrack) => void">
      Callback called with a `MediaStreamTrack` of the virtual computer's audio stream.
    </ParamField>

    <ParamField body="onCursor" type="(e: PeerMouseEvent) => void">
      Callback called when another user moves their mouse cursor on top of the virtual browser. Useful for implementing multiplayer cursors.
    </ParamField>

    <ParamField body="onDisconnect" type="(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.
    </ParamField>

    <ParamField body="onCloseWarning" type="(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.
    </ParamField>

    <ParamField body="onConnectionStateChange" type="(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.
    </ParamField>
  </Expandable>
</ParamField>

[See initialization example.](/client-sdk/javascript/examples#loading-a-virtual-browser)

***

## The HyperbeamClient object

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

```js JavaScript theme={null}
const hb: Promise<HyperbeamClient> = await Hyperbeam(
  container,
  embedURL,
  options
);
```

### Properties

<br />

<ParamField body="hb.userId" type="string">
  The client's user ID. [See
  example.](/client-sdk/javascript/examples#getting-user-id)
</ParamField>

<ParamField body="hb.adminToken" type="string">
  The client’s admin token. [See
  example.](/client-sdk/javascript/examples#setting-admin-token)
</ParamField>

<ParamField body="hb.volume" type="number">
  The local volume of the virtual browser. [See
  example.](/client-sdk/javascript/examples#setting-video-volume)
</ParamField>

<ParamField body="hb.width" type="number">
  The width of the virtual browser in pixels. [See
  example.](/client-sdk/javascript/examples#resizing-the-browser)
</ParamField>

<ParamField body="hb.height" type="number">
  The height of the virtual browser in pixels. [See
  example.](/client-sdk/javascript/examples#resizing-the-browser)
</ParamField>

<ParamField body="hb.maxArea" type="number">
  The maximum virtual browser area that can be allocated in pixels. [See
  example.](//client-sdk/javascript/examples#resizing-the-browser)
</ParamField>

<ParamField body="hb.videoPaused" type="boolean">
  Pauses the video stream of the virtual browser locally. [See
  example.](/client-sdk/javascript/examples#pausing-video-stream)
</ParamField>

<ParamField body="hb.playoutDelay" type="boolean">
  When `playoutDelay` = `true`, input lag increases but smoothness is improved
  and frame drops are reduced.
</ParamField>

<ParamField body="hb.tabs" type="Tabs Object">
  The virtual browser Tabs object. [See
  example.](/client-sdk/javascript/examples#control-tabs-programmatically)
</ParamField>

### Methods

***

#### <Heading hidden>reconnect</Heading>

`hb.reconnect(): void`

Useful in situations where you need to troubleshoot the browser disconnecting. [See example.](/client-sdk/javascript/examples#manual-reconnection)

***

#### <Heading hidden>destroy</Heading>

`hb.destroy(): void`

Tears down network connections and browser events. Always call this *before* removing the container element from the page. [See example.](/client-sdk/javascript/examples#destroying-the-embed)

***

#### <Heading hidden>addRoles</Heading>

`hb.addRoles(userIds, roles, exclusive): Promise<void>`

Adds the list of roles to all the provided user ids.

**Method parameters**

<ParamField body="userIds" type="string[]" required={true}>
  List of user ids
</ParamField>

<ParamField body="roles" type="string[]" required={true}>
  List of roles to be assigned to the provided user ids
</ParamField>

<ParamField body="exclusive" type="bool" required={false} default={false}>
  If set to true, the roles are assigned to all users except the provided list of user ids.
</ParamField>

#### <Heading hidden>removeRoles</Heading>

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.](/client-sdk/javascript/examples#setting-permissions)

**Method parameters**

<ParamField body="userIds" type="string[]" required={true}>
  List of user ids
</ParamField>

<ParamField body="roles" type="string[]" required={true}>
  List of roles to be removed from the provided user ids
</ParamField>

<ParamField body="exclusive" type="bool" required={false} default={false}>
  If set to true, the roles are removed from all users except the provided list of user ids.
</ParamField>

#### <Heading hidden>setPermissions</Heading>

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

<Warning>`setPermissions` is deprecated, please use `addRoles` and `removeRoles`</Warning>

Sets the permission of a user by their ID. The client must have an admin token set to manage user permissions. [See example.](/client-sdk/javascript/examples#setting-permissions)

**Method parameters**

<ParamField body="userId" type="string">
  The user ID to set permissions for.
</ParamField>

<ParamField body="permissionData" type="object">
  All keys can be omitted: if the key is omitted, then the existing value will
  be unchanged.

  <Expandable>
    <ParamField body="priority" type="number" default="0">
      Higher value = higher priority. Users with a higher priority will preempt
      the control of lower priority users.
    </ParamField>

    <ParamField body="idle_timeout" type="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.
    </ParamField>

    <ParamField body="control_disabled" type="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.
    </ParamField>
  </Expandable>
</ParamField>

#### <Heading hidden>sendEvent</Heading>

`hb.sendEvent(event): void`

Sends a keyboard, mouse, or mouse wheel event to the Hyperbeam browser. [See example.](/client-sdk/javascript/examples#send-events-programmatically)

**Method parameters**

<ParamField body="event" type="KeyEvent | MouseEvent | WheelEvent" />

#### <Heading hidden>resize</Heading>

`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.](/client-sdk/javascript/examples#resizing-the-browser)

**Method parameters**

<ParamField body="width" type="number">
  The width of the virtual browser in pixels.
</ParamField>

<ParamField body="height" type="number">
  The height of the virtual browser in pixels.
</ParamField>

#### <Heading hidden>ping</Heading>

`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](/client-sdk/javascript/reference#hyperbeamregioninfo) object. This object refers to the optimal region to spin up a virtual computer based on the client’s location.

```js JavaScript theme={null}
import {getRegionInfo} from "@hyperbeam/web"
...
const regionInfo = await getRegionInfo()
```

[How to use getRegionInfo to optimize server location.](/client-sdk/javascript/examples#optimize-server-location)

### HyperbeamRegionInfo

#### Properties

<br />

<ParamField body="region" type="string">
  Two-letter region code.
</ParamField>

<ParamField body="country" type="string" optional>
  Country code.
</ParamField>