@hyperbeam/iframe
v0.0.6-alpha.2DEPRECATED, 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
- 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)
Homepage
hyperbeam.dev/Metadata
- Unknown
- Whatever
- Ambareesh Balaji
- released 4/6/2022