Your own loading and ending screens

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.

How to listen

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.

The lifecycle: which event comes after which

A session moves through these steps in this order.

  1. session.queued step 1000 · waiting for a machine
  2. session.queuePositionChanged step 1100 · each time the place in the queue changes (may repeat)
  3. session.hostFound step 2000 · a machine was found
  4. session.hostReserved step 3000 · the machine is held for this viewer
  5. build.acquiring step 4000 · your app is copied to the machine (skipped when it is already there)
  6. build.preparing step 5000 · your app is unpacked and prepared
  7. build.started step 6000 · your app is running; the video connection is set up
  8. stream.ready step 7000 · the stream is ready (may wait for a click)
  9. e3ds.listening step 7100 · the stream page accepts messages
  10. build.listening step 7200 · your app accepts messages
  11. stream.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.

All events

Every event is an object. These fields are on all of them:

Some events add their own fields, listed in each event's section below.

session.queued

When: 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.queuePositionChanged

When: 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.hostFound

When: 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.hostReserved

When: 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.acquiring

When: 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.preparing

When: 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.started

When: 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.ready

When: 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.listening

When: the stream page accepts messages from your page.

Before it: stream.ready. After it: build.listening.

Fields: none of its own.

build.listening

When: 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.playing

When: 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.ending

When: 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.stopped

When: 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.expired

When: the session's time limit was reached — and nothing else. session.ending follows.

Fields: none of its own.

stream.failed

When: the video could not start for the viewer.

Fields: none you need.

Show: a "try again" button that reloads your page.

session.error

When: 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.

Showing the viewer's place in the queue

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.

A loading screen

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";
  }
}

An ending screen

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.

A crash-only message

"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:

EventFires forCarries
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.

See it working: our iframe demo

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.

What each part of that file does:

On a Web SDK page the same handler works unchanged — only the listening line differs (e3ds_controller.callbacks.onEvent = handle, see How to listen).

Watch one being built

Build a “press any key to start” screenWatch on YouTube

Related

Last updated