Crash Reporting for Games Shipped as PWA Installs

Shipping a game as an installable progressive web app feels like the best of both worlds: no store review, instant updates, an icon on the home screen. Then the crash reports start arriving and you realize an installed PWA is a far stranger runtime than a tab. It runs in the player's browser engine, not yours. It serves assets from a service worker cache that may be hours or weeks stale. It launches offline. The same code path that works in your dev tab can fail on an old Android WebView with a cache from two releases ago. This post is about capturing enough context to tell those situations apart.

Why installed PWAs crash unlike native builds

A native build ships one engine, one renderer, one set of libraries that you tested. A PWA inherits the player's browser, which could be a current Chrome, a year-old Safari, or an embedded WebView inside some launcher you have never heard of. WebGL contexts get lost when the OS reclaims memory, IndexedDB throws quota errors, and the same WebAudio call behaves differently across engines. The crash you see is often a property of the host, not your code, and you cannot reproduce it without knowing which host produced it.

Installation adds another layer. An installed PWA runs in standalone display mode, sometimes with different storage partitioning and permission behavior than the same site in a tab. Players keep the installed app around for months without ever hard-refreshing, so they accumulate state and cached assets that no fresh visitor ever has. A bug that only fires after the app has been installed and reopened forty times is invisible in your test matrix unless your reports tell you the app was launched standalone.

Service workers and stale caches

The service worker is the single biggest source of PWA-specific crashes, because it decides which version of your game the player actually runs. If your worker caches the HTML shell aggressively but your asset bundle ships a new hash, a player can end up running old JavaScript against new data, or new code against an asset manifest that no longer matches. The result is a load error or a runtime exception that makes no sense against your current source, because the player is not running your current source. They are running a frozen blend of two releases.

Every crash report from a PWA should record the active service worker version, the cache name or asset manifest hash that served the bundle, and whether an update was pending. When you see a cluster of impossible errors, the first thing to check is whether they all share an old cache version. Usually they do, and the fix is a worker update strategy that activates promptly rather than a code change. Without that field you will waste days chasing a bug that does not exist in the code you are reading.

Offline launches and connectivity edges

The headline feature of a PWA is that it launches with no network, and that is exactly where it breaks. Code that quietly assumed a fetch would succeed now throws on the first offline launch. Save sync, leaderboard posts, ad calls, and analytics pings all fail in ways that may or may not be handled. A player on a train who opens your game in a tunnel produces a completely different failure profile than a player on wifi, and if you cannot see their connectivity you cannot tell a real bug from an unhandled offline path.

Connectivity is also not binary. Players hit captive portals, flaky cellular, and the dreaded state where the browser reports online but every request times out. Capturing navigator.onLine at crash time is a start, but pairing it with whether recent network calls succeeded tells the real story. Many PWA crashes are timing bugs around the online and offline transition, where a deferred queue flushes against a half-open connection. You need the connectivity context to even recognize that pattern across reports.

Taming browser and engine variance

Because you do not control the engine, your reports must describe it precisely. The user agent string alone is not enough now that browsers freeze and lie about versions, so capture the rendering engine, major version, platform, and device memory hint where available. Group crashes by engine first and you will often find that ninety percent of a noisy signature comes from one stale browser family, which lets you decide whether to polyfill, guard, or simply show those players an upgrade prompt instead of rewriting working code.

Memory and GPU variance deserve their own attention. WebGL context loss, canvas allocation failures, and audio decode limits cluster hard on low-memory devices. If your reports carry a rough device tier and the GPU renderer string, a crash that looked random resolves into a clean low-end-device story. That distinction changes the fix entirely: it is not a logic bug, it is a resource budget your game exceeds on a class of hardware you can now identify and test against.

Setting it up with Bugnet

Drop the Bugnet web SDK into your PWA and the in-game report button captures the runtime context that makes these crashes legible: the rendering engine and version, standalone display mode, navigator.onLine, the active service worker version, and the cached asset hash, all attached automatically to every report and uncaught exception. Players do not have to describe their browser or know whether they were offline, because the report already carries it. A web-form fallback covers cases where the app itself is too broken to fire its own button.

Bugnet folds duplicate crashes into a single grouped issue with an occurrence count, so a stale-cache error hitting hundreds of installs shows up as one prioritized issue rather than a flood. Filter that group by service worker version or engine and the stale-cache pattern jumps out immediately. Custom fields let you record your build hash and worker generation, so you can confirm at a glance whether a wave of reports is genuinely new or just old installs that have not updated yet, all from one dashboard.

Test the install, not just the tab

Most PWA crashes survive to production because the team only ever tested in a fresh tab with devtools open and the network online. Build a habit of testing the installed app: add it to the home screen, kill the network, relaunch, then ship an update and confirm the worker activates. Keep an old device around with an old browser and a deliberately stale cache, because that device represents a real slice of your players and will surface the bugs your modern dev machine never will.

Treat the service worker update path as a feature with its own tests, not an afterthought. Decide explicitly whether updates apply on next launch or require a prompt, and verify offline launches degrade gracefully instead of throwing. With real crash context flowing in from the field, you can watch a release roll out across engines and connectivity states and catch the stale-cache cluster within hours, long before it becomes the support thread that defines your week.

An installed PWA runs the player's browser and the player's cache, not yours. Capture engine, connectivity, and worker version or you will debug bugs that do not exist in your code.