@hyperbeam/iframe
Advanced tools
The JavaScript frontend library for the Hyperbeam multiplayer browser API.
Unfamiliar with the Hyperbeam API? Read the full documentation here.
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>
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>
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"}}
})
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)
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
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
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
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"
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)
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
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:
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/"})
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:
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)
FAQs
Web client library for the Hyperbeam multiplayer browser API
We found that @hyperbeam/iframe demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.
Security News
The Axios compromise shows how time-dependent dependency resolution makes exposure harder to detect and contain.
Research
A supply chain attack on Axios introduced a malicious dependency, plain-crypto-js@4.2.1, published minutes earlier and absent from the project’s GitHub releases.