Quick answer: Install and configure the Bugnet SDK for HTML5 and web games. Capture screenshots, console logs, and browser info with a few lines of JS.

This getting started Web guide walks you through the setup process step by step. Web games are booming. Whether you are building with Phaser, PixiJS, Three.js, PlayCanvas, or a custom WebGL engine, shipping directly to the browser means zero install friction and instant access for players worldwide. But it also means debugging in the wild is harder than ever. Browser differences, device fragmentation, and the sheer variety of network conditions make it nearly impossible to reproduce every issue your players encounter. That is exactly why we built the Bugnet Web SDK.

This guide walks you through installing and configuring @bugnet/web-sdk for your HTML5 or web-based game. By the end, you will have automatic bug reporting, DOM screenshot capture, console log collection, and full browser and device metadata flowing into your Bugnet dashboard—all in under ten minutes of setup.

Installation

The Bugnet Web SDK is distributed as a standard npm package. Install it into your project alongside your existing dependencies:

Terminal 
npm install @bugnet/web-sdk

If you are using Yarn or pnpm, substitute accordingly:

yarn add @bugnet/web-sdk
# or
pnpm add @bugnet/web-sdk

The package ships with full TypeScript type definitions, so you get autocompletion and type checking out of the box regardless of whether you write TypeScript or JavaScript.

Initialization

Import the SDK and create a new instance with your project credentials. You can find your API key and Game ID in the Bugnet dashboard under Settings → SDK Keys.

JavaScript / TypeScript 
// Import the SDK
import { BugnetSDK } from '@bugnet/web-sdk';

// Create and initialize
const bugnet = new BugnetSDK({
  apiKey: 'YOUR_API_KEY',
  gameId: 'YOUR_GAME_ID',
  trigger: 'shake',
});

bugnet.init();

That is the minimal setup. Once init() is called, the SDK begins listening for the configured trigger, captures console output in the background, and is ready to submit reports. The SDK is lightweight—under 18 KB gzipped—and has zero external dependencies, so it will not bloat your bundle or interfere with your game loop.

Configuring Triggers

A trigger is the action that opens the bug reporting dialog for your players. The SDK supports three built-in trigger types, and you can also invoke the reporter programmatically.

Shake detection is the default. On mobile devices, a physical shake gesture opens the reporter. On desktop browsers, a rapid mouse shake does the same. This is great for playtesting because it requires no UI changes:

const bugnet = new BugnetSDK({
  apiKey: 'YOUR_API_KEY',
  gameId: 'YOUR_GAME_ID',
  trigger: 'shake',
});

Keyboard shortcut lets you assign a key combination. This is ideal for desktop-focused games where you want a discoverable but unobtrusive entry point:

const bugnet = new BugnetSDK({
  apiKey: 'YOUR_API_KEY',
  gameId: 'YOUR_GAME_ID',
  trigger: 'keyboard',
  triggerKey: 'F8',
});

Custom button gives you full control. Pass 'manual' as the trigger and call bugnet.show() from your own UI element—a pause menu button, a settings panel link, or anything else:

const bugnet = new BugnetSDK({
  apiKey: 'YOUR_API_KEY',
  gameId: 'YOUR_GAME_ID',
  trigger: 'manual',
});
bugnet.init();

// Wire up your own button
document.getElementById('report-bug-btn')
  .addEventListener('click', () => bugnet.show());

You can combine approaches. For example, use 'keyboard' as the primary trigger and still call bugnet.show() from a menu button. The SDK handles deduplication and will not open multiple report dialogs simultaneously.

Automatic Console Error Capture

One of the most valuable features of the Web SDK is automatic console error capture. When enabled, the SDK hooks into window.onerror and window.onunhandledrejection to catch uncaught exceptions and failed promises. It also records a rolling buffer of recent console.log, console.warn, and console.error calls so that every bug report includes the context leading up to the issue.

const bugnet = new BugnetSDK({
  apiKey: 'YOUR_API_KEY',
  gameId: 'YOUR_GAME_ID',
  trigger: 'shake',
  captureConsole: true,
  consoleBufferSize: 100,
  autoCapture: {
    errors: true,
    unhandledRejections: true,
  },
});
bugnet.init();

When an unhandled error fires, the SDK automatically creates a bug report draft with the error message, stack trace, the last 100 console entries, and a DOM screenshot—all without the player needing to do anything. You can configure whether these auto-captured reports are submitted silently or shown to the player for review before sending.

Manual Bug Report Submission

Sometimes you want to submit a report programmatically—for example, when your game detects an inconsistent state, when a network request fails unexpectedly, or when an asset fails to load. The SDK exposes a submit() method for exactly this purpose:

// Catch a failed asset load and report it
async function loadLevel(levelId) {
  try {
    const data = await fetch(`/assets/levels/${levelId}.json`);
    if (!data.ok) throw new Error(`HTTP ${data.status}`);
    return await data.json();
  } catch (err) {
    bugnet.submit({
      title: `Failed to load level ${levelId}`,
      description: err.message,
      severity: 'high',
      metadata: {
        levelId,
        playerProgress: getPlayerProgress(),
        timestamp: Date.now(),
      },
    });
    showFallbackScreen();
  }
}

Manual submissions include the same automatic context as player-initiated reports: console log buffer, browser and device info, and a DOM screenshot at the moment of submission. You can attach additional metadata as a flat object of key-value pairs, which becomes searchable and filterable in the dashboard.

What Gets Captured

Every bug report submitted through the Web SDK—whether triggered by the player, by an automatic error, or by a programmatic call—includes a rich set of contextual data:

Framework Compatibility

The Web SDK is framework-agnostic. It works with any HTML5 game engine or web framework. We have tested it extensively with Phaser 3, PixiJS, Three.js, Babylon.js, PlayCanvas, and Construct 3 exports, as well as plain Canvas 2D games. If your game runs in a browser, the SDK will work.

For single-page applications built with React, Vue, or Svelte that wrap a game canvas, the SDK integrates cleanly. Initialize it once at the application root and it will persist across route changes. The screenshot capture is smart enough to include the full page, not just the framework's root element.

"We dropped the Bugnet snippet into our Phaser 3 game and had our first real player bug report—complete with a screenshot of the broken tilemap—within an hour of deploying to our staging environment."

Getting the Most Out of Web Bug Reports

Here are a few tips to maximize the value of bug reports from your web game:

Web games deserve the same quality of bug reporting tooling that native games have had for years. With the Bugnet Web SDK, you get exactly that: automatic capture, rich context, and a dashboard built for game developers. Your players will thank you—even if they never know the SDK is there.