Developer documentation

Browser loader API

Mount options, controller methods, real commands and host events.

The browser global

Loading the generated /embed/v1.js script installs window.RapidEye. It is a browser global, not a package import. Load one RapidEye environment on each page.

Member	Contract
version	The string 1 for this loader.
origin	The origin inferred from the loaded script URL.
mount(element, options)	Creates an iframe in a DOM element and returns its controller. Remounting the same element destroys its previous controller.
get(element)	Returns the existing controller or null. It does not mount an element or wait for the async loader.

A reusable browser loading helper

Mount options

Option	Value	Behavior
experienceId	Published experience UUID; required.	Selects the experience.
grant	A fresh server-signed string for private access; otherwise omitted or null.	Delivered in the validated initialization message, not the iframe URL.
aspectRatio	CSS aspect-ratio string; default 16 / 9.	Initial wrapper ratio before runtime resize messages set its height.
minHeight	Finite number of pixels, at least zero; default 0.	Minimum wrapper height.
theme	Compatibility value dark or light.	Accepted but currently does not change presentation.

The wrapper fills its container width. Set the container layout in your own CSS. Unknown options do not create additional capabilities.

Controller methods

Member	Behavior
iframe	The created HTMLIFrameElement. Keep the wrapper permission and origin settings intact.
on(event, handler)	Registers a handler and returns an unsubscribe function. Handlers receive the payload without protocol fields.
send(command, payload)	Sends a validated host command to the hosted runtime. Invalid commands or payloads throw synchronously.
destroy()	Removes the wrapper/frame and registered host listeners. Repeated calls are safe.

destroy is UI teardown, not a browser-task cancellation or data-deletion operation. A viewer should use Stop inside Chat when a task must end.

There are no controller play(), pause(), seek(), cancelTask() or getTranscript() methods. Use send for documented playback commands.

Commands

send command	Payload	Current behavior
play	{}	Requests playback; browser media policies still apply.
pause	{}	Pauses the video.
seek	{ seconds: 12.5 }	Seeks to a finite, nonnegative number of seconds.
ping	{ id: a string }	Produces a matching pong from the host bridge.
theme	{ theme: dark or light }	Accepted compatibility message; no current visual effect.

Observe setup and send supported controls

const embed = window.RapidEye.mount(document.querySelector('#player'), {
  experienceId: 'EXPERIENCE_ID',
  aspectRatio: '16 / 9',
  minHeight: 240,
});
const unsubscribe = embed.on('ready', ({ experienceId, revision }) => {
  console.log('Experience setup completed', experienceId, revision);
});
embed.on('pong', ({ id }) => console.log('Bridge reply', id));
// Connect these application functions to your own controls.
function pauseFromYourControls() {
  embed.send('pause', {});
}
function seekFromYourControls(seconds) {
  embed.send('seek', { seconds });
}
function pingFromYourControls(id) {
  embed.send('ping', { id });
}
// On teardown: unsubscribe(); embed.destroy();

Events

on event	Payload	Meaning
ready	experienceId, revision, capabilities	Viewer/bootstrap setup completed. Not a video-loaded event.
resize	height in pixels	The runtime reports height; the wrapper applies it automatically.
state	state, currentTime in seconds	playing or paused transition snapshot. Not a continuous timeupdate stream.
navigate	url, reason	Reports external navigation already opened by the viewer interaction. Current shared viewer emits reason link.
error	code, message	Runtime setup/session/bootstrap failure. Not a complete feed of every chat or media HTTP error.
pong	id	Reply to a matching ping.

The protocol schema also accepts state ended and navigation reasons booking/sign_in, but current viewer presentation does not emit those values. Do not rely on them as completion signals.

hello is an internal handshake handled by the wrapper, not an application event. No host event exposes browser-task progress, task completion or chat transcripts.

Both sides validate sender origin, source window and payload shape. Unknown messages are dropped. navigate is an observation, not a cancelable interception hook.