Handling App Crash Message in iFrame

This guide walks through adding a message that appears only when the streamed Unreal app actually crashes, not for other session-end reasons like timeouts, wrong passwords, or expired links.

Overview

Eagle3D's streaming client sends your page two relevant postMessage events when a session ends:

• handleStreamerDisconnected: fires only when the app process itself stopped (crash, unexpected close, or its machine went down). Carries no message text.

• redirectingWithMessage: fires reliably whenever a session ends, for any reason, and carries a human-readable event.data.message string.

Because only handleStreamerDisconnected is crash-specific, the approach here is: set a flag when it fires, then only act on redirectingWithMessage if that flag is set.

Note: this filtering approach has a real limitation covered in Important Notes at the end of this document, read that section before shipping it.

Now follow the steps below:

Step 1. Add the Overlay Markup to Your HTML

Add a hidden overlay element inside the same container as the <iframe>, so it can be shown on top of it:

<div
id="sessionEndOverlay"
style="
 display: none;
 visibility: visible;
 position: absolute;
 left: 0; right: 0; top: 0; bottom: 0;
 background: rgba(20,20,20,0.96);
 color: #fff;
 z-index: 10;
 flex-direction: column;
 align-items: center;
 justify-content: center;
 text-align: center;
 font-family: sans-serif;
 "
>
<div style="font-size: 72px; line-height: 1;">&#128546;</div>
<div id="sessionEndOverlayMessage" style="font-size: 20px; margin-top: 16px; maxwidth: 80%;"></div>
</div>

Two details matter here:

• visibility: visible must stay on this div even though its parent ( #content ) starts as visibility: hidden. If the crash happens before the parent becomes visible, this override is what still lets your overlay show through.

• display: none is what keeps it hidden until you flip it to flex in JavaScript.

Step 2. Add a Crash Flag

At the top of message.js , outside the handler function, add a flag that tracks whether a crash was actually reported:

let appCrashed = false;

Step 3. Set the Flag on handleStreamerDisconnected

Find (or add) the handleStreamerDisconnected case in your messageHandler switch statement, and set the flag there:

case "handleStreamerDisconnected":
appCrashed = true;
break;

Note: this event can arrive late or not fire at all, see point 4 in Important Notes. Don't treat this step alone as a guarantee the flag will be set in time.

Step 4. Gate redirectingWithMessage on the Flag

Update the redirectingWithMessage case so it only shows the overlay when appCrashed is true . Otherwise it just breaks out and does nothing:

case "redirectingWithMessage": {
if (!appCrashed) break; // not a crash — ignore
const overlay = document.getElementById("sessionEndOverlay");
const overlayMsg = document.getElementById("sessionEndOverlayMessage");
if (overlayMsg) overlayMsg.innerText = "The app crashed. Please refresh to
reconnect.";
if (overlay) overlay.style.display = "flex";
break;
}

Note: never branch your code on the text of event.data.message itself, see point 2 in Important Notes. This step only checks the appCrashed flag, which is the supported way to do this.

Step 5. Test It

1. Load the page and start a session normally.

2. Trigger an app crash (or ask your engineer how to simulate one in your test environment).

3. Confirm the overlay appears with your crash message.

4. Separately, test a non-crash session end (e.g. let a session time out, or use an expired link) and confirm the overlay does not appear in that case.

5. Repeat the crash test a few times, because of point 3 below, a single successful test isn't proof the flag will always be set in time.

Fallback: Show the Overlay for Any Session End

If missing the crash message occasionally is worse than showing it too broadly, the safer default, and what Eagle3D's own demo does, is to skip the flag entirely and always show the overlay on redirectingWithMessage , using its event.data.message text. That guarantees the user always sees something when a session ends, at the cost of no longer distinguishing "crash" from other end-of-session reasons:

case "redirectingWithMessage": {
const overlay = document.getElementById("sessionEndOverlay");
const overlayMsg = document.getElementById("sessionEndOverlayMessage");
if (overlayMsg) overlayMsg.innerText = event.data.message || "The stream has
ended.";
if (overlay) overlay.style.display = "flex";
break;
}

Important Notes

Before shipping this implementation, be aware of the following limitations. These limitations affect how reliably a crash-only message can be displayed:

1. There is currently no session-end reason code. Eagle3D provides a short, human-readable display message, but does not provide a specific reason code such as crash, afk, or wrong password. If your integration needs to reliably distinguish between these reasons in code, this is not currently supported.
   

2. Do not parse or match against event.data.message. This value is intended for human-readable display and should not be used by your application logic. For example, do not check whether the message contains "crash". The wording of the message may change without notice. (Relevant to Step 4.)
   

3. Do not assume that handleStreamerDisconnected and redirectingWithMessage arrive together or in a specific order. Treat these as independent events. This directly affects the crash flag approach in Steps 2 to 4: because the event order is not guaranteed, handleStreamerDisconnected may not have been received before redirectingWithMessage, even when an actual crash occurs. (Relevant to Steps 2, 3, and 4.)
   

4. handleStreamerDisconnected may arrive late or may not arrive at all. This event is intended as an optional signal indicating whether the application or streamer is still running. It should not be treated as a guaranteed event for implementing a user-facing feature. (Relevant to Step 3.)
   

5. Your page cannot stop or delay the session from ending. There is no way to intercept these events and cancel the session shutdown. Design your overlay to appear after the session-ending event rather than relying on the ability to prevent or delay the session from ending. (Relevant to Step 1.)
   

6. redirectingWithMessage is the recommended event for a general "stream ended" screen. It reliably fires when a session ends, regardless of the reason, which is why the fallback approach above, showing the overlay for any redirectingWithMessage event rather than only for crashes, is the approach used by Eagle3D's own demo by default.
   

Bottom line: The crash flag approach in Steps 1 to 5 is a best-effort way to filter for crashes using the only crash-specific signal currently exposed by Eagle3D. It is not guaranteed to detect every crash, primarily because the event order is not guaranteed and handleStreamerDisconnected may arrive late or not at all. If your use case requires reliable, code-inspectable session-end reasons, contact Eagle3D Support before relying on this behavior in production.

Need help?

If you need any assistance, feel free to reach out through any of the following channels:

🛠️ Support Portal: Contact Our Support Team

💬 Discord Community (Faster Support): Join Our Discord Community

📧 Email Support: support@eagle3dstreaming.com

🆓 Get Started for free

Follow us on:

Facebook | GitHub | LinkedIn | YouTube