Crash Reporting for Web Games on Game Portals

Game portals distribute HTML5 web games embedded in their own sites, running your game in an iframe alongside the portal interface, ads, and SDK, reaching the massive casual audiences these portals draw. Your game runs inside someone else page, subject to the iframe sandbox, the portal SDK integration for ads and features, and the portal constraints, on top of all the usual web game failure modes. Setting up crash reporting for a portal-hosted web game means capturing the JavaScript errors within the embed, with the browser and portal-integration context that the embedded, portal-mediated environment requires.

Portal games run inside someone else's site

A web game on a portal runs embedded in the portal site, your HTML5 game loaded in an iframe alongside the portal interface, ads, and SDK, rather than on your own page. This means your game runs inside someone else environment, subject to the iframe sandbox and its constraints, integrated with the portal SDK for ads, analytics, and features, and dependent on how the portal embeds and serves it. The portal mediates the environment your game runs in.

This embedded, portal-mediated nature shapes crash reporting on top of the usual web game concerns. Your game still fails as a web game, with silent JavaScript errors, browser variability, and the web constraints, but now within the portal iframe and integration, which add their own layer. And portals reach massive casual audiences, so the scale and breadth are large. Understanding that a portal game runs inside someone else site, within an iframe and the portal SDK, reaching a casual audience at scale, is the foundation for capturing its crashes, which must work within the embedded environment.

Capture errors within the embed

Capture errors from your portal-hosted game by hooking the JavaScript error handling within your game running in the iframe, the global error and unhandled rejection handlers, so the silent JavaScript errors that would land in the console and stop the game are captured. This is the standard web error capture, working within your game code in the iframe, which you control even though the surrounding page is the portal.

The errors are silent as in any web game, the player sees the embedded game freeze or stop and likely moves on, since portal audiences are casual and have many other games a click away, so automatic capture is the only way to learn about the failures. Capture the error and stack trace, with source maps for your minified build, within the embed. Capturing errors within the embed, hooking your game error handling in the iframe, is the core of portal game crash reporting, surfacing the silent failures of a game running inside the portal that you would otherwise never see.

Account for the portal SDK integration

Portals provide an SDK that your game integrates for ads, analytics, events, and features, and this integration is an additional layer that can be a crash source, an SDK call that fails, an ad integration that errors, a portal feature that misbehaves. Capture context around the portal SDK integration where relevant, so integration-related errors are identifiable as distinct from your core game errors.

The ad integration in particular is common in portal games, since ads are how the portal and often the developer monetize, and ad-related errors, an ad that fails to load, an ad SDK error, an issue resuming after an ad, are a portal-specific failure mode. Capture the integration context so these are distinguishable. Accounting for the portal SDK integration, especially the ads, capturing its context so integration errors are identifiable, covers the portal-specific layer of crash reporting, beyond the web game errors that are the bulk, ensuring the portal integration issues are caught alongside your game errors.

Capture the browser and portal context

Like any web game, a portal game runs across the browser matrix, and crashes cluster by browser and device, so capture the browser, OS, and device context on every error. The massive casual audience portals reach brings a very wide range of browsers and devices, including many on mobile and on lower-end hardware, so the device and browser breadth is large and the context essential for clustering crashes.

Capture which portal the game is running on too, if you distribute on multiple portals, since the embedding and integration differ by portal and a crash specific to one portal points at that portal embedding or SDK. The browser context handles the web variability and the portal context handles the distribution variability. Capturing the browser and portal context lets you cluster portal game crashes by both the browser environment and the portal, identifying the browser-specific failures and the portal-specific ones across the wide casual audience and the multiple portals a web game may be distributed on.

Setting it up with Bugnet

Bugnet web SDK hooks the JavaScript error handling within your game in the portal iframe, capturing the silent errors with the browser, OS, and device context, and you add custom fields for the portal and the SDK integration context. The errors flow into one dashboard, even from your game embedded in the portal site, surfacing the failures the casual portal audience would never report.

Group identical errors into occurrence counts to handle the scale of the portal audience, and use the portal and browser context to cluster crashes by portal and environment. Because portal games run silently in an iframe to a massive casual audience, the captured error data with portal and browser context is what gives you visibility, surfacing the silent failures and the portal-integration issues across the wide audience and the portals you distribute on, which automatic capture within the embed is essential for since the casual portal audience clicks away rather than reporting.

Test in the portal environment

Because a portal game runs in the portal embedded environment with its SDK and constraints, test in that environment, the actual portal embed with the portal SDK and ads, not just your standalone build, since the iframe sandbox, the portal SDK integration, and the ad behavior only manifest in the real portal embedding. A game that runs fine standalone can hit issues in the portal iframe or with the portal SDK that only testing there reveals.

Test across the browsers and devices the portal audience uses, especially mobile and lower-end devices given the casual breadth, and test the ad integration and resume behavior, since ads are a common portal failure point. Pair the portal-environment testing with your captured error data, which surfaces the failures across the wide audience and the portal integration you cannot fully test. Together they let you support a portal-hosted web game across the massive casual audience and the portal environment, with the embedded, SDK-integrated, ad-supported failures, where portal games specifically fall down, kept under control.

Portal games run silently in someone else's iframe to a casual audience. Capture errors in the embed and the portal SDK context.