A wait and a failure are the two moments your stream looks least like your product. Both are replaceable: Eagle 3D Streaming tells your page what is happening, step by step, and you decide what appears. An iframe page and a Web SDK page receive the very same events — only the place you listen differs.
Every event is an object with a type. Write one handler and connect it the way your page embeds the stream:
function handle(event) {
if (!event || typeof event !== "object") return;
switch (event.type) {
case "session.queued":
// your loading screen
break;
case "stream.playing":
// hide it
break;
}
}
// Connect it - the same code works on a Web SDK page and on an iframe page
if (typeof e3ds_controller !== "undefined" && e3ds_controller.callbacks) {
// Web SDK page: the SDK hands each event to this callback
e3ds_controller.callbacks.onEvent = handle;
} else {
// iframe page: the stream in the iframe posts each event to your page
window.addEventListener("message", function (e) {
// only listen to the stream itself, not to other windows
if (!/(^|\.)eagle3dstreaming\.com$/.test(new URL(e.origin).hostname)) return;
handle(e.data);
});
}
e3ds_controller exists only on a page that loads the Web SDK, so
the check picks the right way to listen by itself. On a Web SDK page, run this
code after the Web SDK script has loaded. The handler stays
the same either way.
A session moves through these steps in this order.
session.queued step 1000 · waiting for a machinesession.queuePositionChanged step 1100 · each time the place in the queue changes (may repeat)session.hostFound step 2000 · a machine was foundsession.hostReserved step 3000 · the machine is held for this viewerbuild.acquiring step 4000 · your app is copied to the machine (skipped when it is already there)build.preparing step 5000 · your app is unpacked and preparedbuild.started step 6000 · your app is running; the video connection is set upstream.ready step 7000 · the stream is ready (may wait for a click)e3ds.listening step 7100 · the stream page accepts messagesbuild.listening step 7200 · your app accepts messagesstream.playing step 8000 · the video is playing
At any moment (no sequence): something can end the
session. Then build.stopped,
session.expired,
stream.failed or
session.error may arrive, and
session.ending always comes last.
Every event is an object. These fields are on all of them:
type — the event name, for example "session.queued"phase — session, build, stream or e3dssequence — the step number from the lifecycle above (an order, not a time; none for the "at any moment" events)Some events add their own fields, listed in each event's section below.
session.queuedsession.queuePositionChangedsession.hostFoundsession.hostReservedbuild.acquiringbuild.preparingbuild.startedstream.readye3ds.listeningbuild.listeningstream.playingsession.endingbuild.stoppedsession.expiredstream.failedsession.errorsession.queuedWhen: the viewer has opened the link and is waiting for a free machine. The first event of a session.
Before it: nothing. After it: session.queuePositionChanged (if they wait) or session.hostFound.
Fields: queuePosition — the viewer's place in the queue (1 = next).
Show: your loading screen, and "You are number N in the queue".
session.queuePositionChangedWhen: the viewer's place in the queue changed while they wait. Sent every time it changes, so it can arrive many times.
Before it: session.queued. After it: another session.queuePositionChanged, or session.hostFound.
Fields: queuePosition (the new place) and queueTotal (how many are waiting for the same app).
Show: update the number, for example "You are 2 of 3".
session.hostFoundWhen: a machine was found for the viewer; the wait in the queue is over.
Before it: session.queued. After it: session.hostReserved.
Fields: none of its own.
Show: hide the queue number; "Starting…".
session.hostReservedWhen: that machine is now held for this viewer. Arrives straight after session.hostFound — treat the two as one moment.
Before it: session.hostFound. After it: build.acquiring or, if the app is already on the machine, build.preparing.
Fields: none of its own.
build.acquiringWhen: your app is being copied to the machine. Only when it is not there yet — a machine that already has it skips this step.
Before it: session.hostReserved. After it: build.preparing.
Fields: percent — how much is copied (0–100).
Show: a progress bar for the copy.
build.preparingWhen: your app is being unpacked and prepared on the machine.
Before it: build.acquiring or session.hostReserved. After it: build.started.
Fields: percent (0–100).
Show: a second progress bar — copying and preparing are separate stages, not one bar filling up.
build.startedWhen: your app has started and the video connection is being set up.
Before it: build.preparing. After it: stream.ready.
Fields: none you need.
Show: "Almost ready…".
stream.readyWhen: the stream is ready. If the browser needs a click before it plays video, it is waiting for that click now.
Before it: build.started. After it: e3ds.listening, build.listening, stream.playing.
Fields: none of its own.
Show: your own "press to start" if you want one.
e3ds.listeningWhen: the stream page accepts messages from your page.
Before it: stream.ready. After it: build.listening.
Fields: none of its own.
build.listeningWhen: your app can receive data from your page. Send nothing to your app before this event.
Before it: e3ds.listening. After it: stream.playing.
Fields: none of its own.
Do: send your first message to the app.
stream.playingWhen: the video is playing. The last step of a normal start.
Before it: build.listening. After it: only the "at any moment" events, when the session ends.
Fields: none of its own.
Show: hide your loading screen.
session.endingWhen: the session is ending, for any reason — a crash, an idle timeout, an expired link, a wrong password, the time limit. Always the last event.
Fields: message — the reason, written for the viewer.
Show: your ending screen with that message (see An ending screen).
build.stoppedWhen: your app's process stopped — a crash, an unexpected close, or the machine going down. session.ending follows.
Fields: none (no text).
Use: to tell a crash apart from other endings (see A crash-only message).
session.expiredWhen: the session's time limit was reached — and nothing else. session.ending follows.
Fields: none of its own.
stream.failedWhen: the video could not start for the viewer.
Fields: none you need.
Show: a "try again" button that reloads your page.
session.errorWhen: the session could not continue because of an error and the stream page is leaving.
Fields: none you need. session.ending carries the readable message.
function handle(event) {
const box = document.getElementById("queueText");
if (event.type === "session.queued" || event.type === "session.queuePositionChanged") {
const n = event.queuePosition;
box.textContent = n <= 1
? "You are next - starting soon."
: "You are number " + n + " in the queue.";
}
if (event.type === "session.hostFound") {
box.textContent = "Starting your session...";
}
}
The number counts only viewers waiting for the same app,
and goes down as the people ahead of the viewer get a machine. When it
reaches the front, session.hostFound follows.
Show it when you load the stream, hide it when the video plays.
// show your loading screen at the moment you load the stream ...
document.getElementById("myLoadingScreen").style.display = "flex";
// ... and hide it, or switch to an ending screen, when the stream says so
function handle(event) {
if (event.type === "stream.playing") {
document.getElementById("myLoadingScreen").style.display = "none";
}
if (event.type === "session.ending") {
document.getElementById("mySessionEndedText").textContent = event.message;
document.getElementById("mySessionEnded").style.display = "flex";
}
}
By default the platform shows its own "session ended" page. Because your screen is yours, you can put a start a new session button on it — which the default screen does not offer, and which is the single most useful thing to add.
Build it on session.ending. It fires for every way a session
ends — a crash, an idle timeout,
an expired link, a wrong password, the time limit — and its
message says which, so one handler and one screen cover all of
them. Show that text rather than inventing your own: it is written for the
person reading it, and it is the only part that knows what actually happened.
Every message a session can end with
lists what it can say.
"Something went wrong" on a session that simply timed out is worse than nothing: a viewer whose hour ran out is not looking at a fault, and telling them they are costs you a support ticket and their confidence. If you want a message for a genuine crash and nothing else, you need two events together, because neither is enough alone:
| Event | Fires for | Carries |
|---|---|---|
build.stopped |
Only the app process stopping — crash, unexpected close, machine down. | No text. |
session.ending |
Every session end, for any reason. | A readable message. |
Set a flag when build.stopped arrives, and when
session.ending follows, show your crash message only if that
flag is set.
Our public iframe demo listens for these events and reacts to them. Open it, start a stream, and watch the queue place, the loading text and the ending screen change; then read the code that does it — in your browser (right-click → View page source, or the developer tools’ Sources tab) or on GitHub.
js/iframe-events.js — all of the event handling is in this one file.What each part of that file does:
window.addEventListener("message", …), the iframe line from How to listen.handlePlatformEvent: one switch on the event type.session.queued and session.queuePositionChanged call showQueueStatus (line 119) with queuePosition.stream.ready and stream.playing hide the loading screen and show the stream.session.ending shows its message through showSessionEndedScreen (line 191), which also has a start again button.session.expired, stream.failed and session.error.
On a Web SDK page the same handler works unchanged —
only the listening line differs (e3ds_controller.callbacks.onEvent = handle,
see How to listen).
Last updated