This package has been deprecated

Author message:

please use https://www.npmjs.com/package/@hyperbeam/web instead

@hyperbeam/iframe

DEPRECATED, please use @hyperbeam/web instead

The JavaScript frontend library for the Hyperbeam multiplayer browser API.

Unfamiliar with the Hyperbeam API? Read the full documentation here.

Table of Contents

• Features
• Installation
• Example
• API
  • Loading multiplayer browser
  • Setting video volume
  • Getting user ID
  • Pausing video stream
  • Setting admin token
  • Setting permissions
  • Send events programmatically
  • Control tabs programmatically
  • Listen to tab events

Features

• Connect to a multiplayer browser
• Control browser navigation programmatically
• Query browser state and listen to events
• Manage user control permissions
• Set local multiplayer browser volume

Installation

Using npm:

$ npm install @hyperbeam/web --save

Using unpkg:

<script type="module">
  import Hyperbeam from "https://unpkg.com/@hyperbeam/web@latest/dist/index.js"
  // ...
</script>

Example

You can save this code snippet as example.html and run it in your browser. Make sure you set the embed URL variable to the response data from the REST API.

<div style="font-family: Arial">
  <button id="reload">Reload</button>
  <button id="back">Go Back</button>
  <button id="forward">Go Forward</button>
  <button id="youtube">Open Youtube.com</button>
  Volume: <input type="range" min="0" max="100" value="100" id="range">
  <p>User ID: <span id="userId"></span></p>
  <p>Current website: <span id="currentSite"></p>
</div>
<iframe id="container" style="height:720px;width:1280px"></iframe>
<script type="module">
  import Hyperbeam from "https://unpkg.com/@hyperbeam/web@latest/dist/index.js"
  // TODO: Set the embedURL variable
  const embedURL = "<your-embed-url>"
  const hb = await Hyperbeam(container, embedURL)
  userId.innerText = hb.userId
  reload.addEventListener("click", () => {
    hb.tabs.reload()
  })
  back.addEventListener("click", () => {
    hb.tabs.goBack()
  })
  forward.addEventListener("click", () => {
    hb.tabs.goForward()
  })
  youtube.addEventListener("click", () => {
    hb.tabs.update({ url: "https://youtube.com" })
  })
  range.addEventListener("change", (e) => {
    hb.volume = e.target.value / 100
  })
  hb.tabs.onUpdated.addListener((tabId, changeInfo) => {
    if (changeInfo.title) {
      currentSite.innerText = changeInfo.title
    }
  })
</script>

API Reference

Loading multiplayer browser

Hyperbeam(container: HTMLIFrameElement | HTMLDivElement, embedURL: string, opts?: HyperbeamOptions): Promise<HyperbeamClient>

Creates a new Hyperbeam client.

// The embedURL is retrieved from the REST API
// Documentation for the REST API can be found here:
// hyperbeam.support/API-Design-eb9874bd1ef54c22ba7197324ce22231
const embedURL = "https://abc.hyperbeam.com/foo?token=bar"
const container = document.getElementById("container-id")

const hb = await Hyperbeam(container, embedURL, {
  // Number of milliseconds until the request to the multiplayer browser times out.
  // If the request times out, the returned promise will be rejected.
  timeout: 5000, // default = 2000

  // An admin token returned from the REST API that will grant this user
  // access to managing user permissions and programmatic navigation.
  adminToken: "admin_token_from_rest_api_response",

  // Starting volume of the multiplayer browser
  volume: 0.2,         // default = 1.0

  // Starting video pause state of the multiplayer browser
  videoPaused: false,  // default = false

  // Data to be provided to your webhook endpoint if you're using webhook authentication
  webhookUserdata: {myAppData: {user: "your-app-user-id"}}
})

Destroying the embed

hb.destroy()

Tears down network connections and browser events. Always call this before removing the container element from the page.

const hb = await Hyperbeam(container, embedURL)
setTimeout(() => {
  hb.destroy()
}, 10_000)

Setting video volume

hb.volume = 0.5

Sets the volume for the multiplayer browser locally. Volume changes only apply to the local user. This setting is not persisted on refreshing the page.

const hb = await Hyperbeam(container, embedURL)
// Valid values range from 0.0 to 1.0
hb.volume = 0.5        // default = 1.0
console.log(hb.volume) // Get the local volume value

Getting user ID

hb.userId: string

Gets the client's user ID. A "user" is defined as a single connection to the multiplayer browser. If a person has multiple tabs connected to the multiplayer browser, each tab with an active connection will be assigned a different user ID.

const hb = await Hyperbeam(container, embedURL)
console.log(hb.userId) // A unique string identifying the user

Pausing video stream

hb.videoPaused = true

Pauses/resumes the video stream for the multiplayer browser locally. Useful if only the audio component is of interest and you want to minimize CPU usage.

const hb = await Hyperbeam(container, embedURL)
hb.videoPaused = true       // Pause the video stream
hb.videoPaused = false      // Resume the video stream
console.log(hb.videoPaused) // Get the video stream pause state

Setting admin token

hb.adminToken = "adminToken"

Sets the client's admin token. The client must have an admin token set to manage user permissions and control the tabs programmatically.

// You can provide the admin token during initialization
const hb = await Hyperbeam(container, embedURL, {
  adminToken: "admin_token_from_rest_api_response"
})

// In some situations, you may want to promote the user to
// an admin after initialization. For example, promoting a "user" to a "moderator".
const hb = await Hyperbeam(container, embedURL)
hb.adminToken = "admin_token_from_rest_api_response"

Setting permissions

hb.setPermission(userId: string, permissionData: PremissionData): Promise<void>

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

// You can provide the admin token during initialization
const hb = await Hyperbeam(container, embedURL, {
  adminToken: "admin_token_from_rest_api_response"
})

const targetUserId = "a_user_id"

// All keys can be omitted: if the key is omitted, then the existing value will be unchanged
const permissions = {
  // Higher value = higher priority
  // Users with a higher priority will preempt the control of lower priority users.
  priority: 2,           // default = 0

  // 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
  // multiplayer browser again.
  idle_timeout: 3000,    // default = 0

  // 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.
  control_disabled: true // default = control_disable_default (see REST API)
}

hb.setPermissions(targetUserId, permissions)

Send events programmatically

hb.sendEvent(event: KeyEvent | MouseEvent | WheelEvent): void

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

const keyEvent = {
  type: "keydown", // type can be set to "keydown" and "keyup"
  // String denoting which key is pressed.
  // See https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values
  key: "A",
  ctrlKey: true // Boolean indicating if the Ctrl key is pressed. Default is false.
  metaKey: false // Boolean indicating if the Meta key is pressed. Default is false.
}

const mouseEvent = {
  type: "mousedown" // type can be set to "mousemove", "mousedown", and "mouseup"
  x: 0.5, // The mouse's X position as a ratio, with a range of [0, 1]
  y: 0.5, // The mouse's Y position as a ratio, with a range of [0, 1]
  // Number that indicates which button was pressed on the mouse. Default is 0.
  // See https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button
  button: 2
}

const wheelEvent = {
  type: "wheel", // Mouse wheel event, used for scrolling up or down
  deltaY: 20 // Positive value signifies scrolling down
}

hb.sendEvent(keyEvent) // Send CTRL+A keystroke
hb.sendEvent(mouseEvent) // Right-click the center of the screen (0.5, 0.5)
hb.sendEvent(wheelEvent) // Scroll down

Control tabs programmatically

Hyperbeam's tab API mirrors Chrome extension tab API, found here.

Rather than calling chrome.tabs.create({ active: true }), you will would call hb.tabs.create({ active: true }).

We support the following methods:

• tabs.create
• tabs.detectLanguage
• tabs.discard
• tabs.duplicate
• tabs.get
• tabs.getZoom
• tabs.getZoomSettings
• tabs.goBack
• tabs.goForward
• tabs.group
• tabs.highlight
• tabs.move
• tabs.query
• tabs.reload
• tabs.remove
• tabs.setZoom
• tabs.setZoomSettings
• tabs.ungroup
• tabs.update

const hb = await Hyperbeam(container, embedURL)

// Create a tab
const tab = await hb.tabs.create({ active: true })

// Duplicate a tab
const tab2 = await hb.tabs.duplicate(tab.id)

// Set the URL of the active tab
const updatedTab = await hb.tabs.update({url: "https://hyperbeam.dev/"})

Listen to tab events

Hyperbeam's tab event listener API mirrors Chrome extension tab API, found here.

Rather than calling chrome.tabs.onCreated.addListener((tab) => {}), you will would call hb.tabs.onCreated.addListener((tab) => {}).

We support the following events:

• tabs.onActivated
• tabs.onCreated
• tabs.onHighlighted
• tabs.onMoved
• tabs.onRemoved
• tabs.onReplaced
• tabs.onUpdated
• tabs.onZoomChange

const hb = await Hyperbeam(container, embedURL)

function onTabCreated(tab) {
  console.log(tab.id)
}

// Listen for when a new tab is created
hb.tabs.onCreated.addListener(onTabCreated)

// Create a new tab
await hb.tabs.create({ active: true })

// Remove the event listener
hb.tabs.onCreated.removeListener(onTabCreated)