Developer guide

Installation and upgrades

Choose the approved SDK artifact, install the right CLI, and keep the application and replay environment reproducible.

Access and versions

These beta releases are available from pub.dev, Maven Central, Swift Package Manager and npm. Create a project in the console and generate an SDK token for your app (Project Settings › Keys › SDK tokens), then sign the CLI in with bugcapsule login, which opens your browser to approve. SDKs and both CLIs use the Bug Capsule Proprietary License; use, copying, modification and distribution require prior written permission.

Component	Version	Install source	Requirements
Flutter + multi-runtime CLI	0.4.1-beta.5	pub.dev	Flutter ≥3.35; Dart ^3.9; git for source-pinned replay
Android modules and Gradle plugin	0.4.1-beta.4	Maven Central: `io.github.bugcapsule`	JDK 17, Android SDK; minSdk 23; emulator for replay
iOS	0.4.1-beta.2	SwiftPM: v0.4.1-beta.2	macOS/Xcode, Swift 6, iOS 15+; simulator for CLI replay
Web, React, web replay and source-map CLI	0.4.0-beta.2	npm: `@bugcapsule/web`, `@bugcapsule/react`, `@bugcapsule/web-replay`, `@bugcapsule/cli`	Node ≥20 for tooling; React ≥18 for helpers; Chromium for replay

Pin the exact beta version and commit your dependency lockfiles. Keep all native modules on the same release.

SDK tokens and the status API are included in these releases. Use the SDK token from your dashboard for a new integration. Existing explicit API URL and ingest key configuration remains supported.

Install the replay CLI

Even Android, iOS and web developers need Flutter installed for the Dart CLI because its package depends on Flutter. Install the published package:

flutter --version
dart pub global activate bug_capsule 0.4.1-beta.6
bugcapsule --version
bugcapsule --help

If the shell cannot find bugcapsule, add the pub cache's bin directory to PATH (normally ~/.pub-cache/bin on macOS/Linux; use your configured PUB_CACHE when set), then open a new shell. On Windows, use the pub cache location reported by activation. An app already depending on the package can use dart run bug_capsule:bugcapsule --help.

Install your platform

Continue with Flutter, Android, iOS or Web & React. To have a coding agent such as Claude Code or Cursor do it in your repository, use the prompts in Set up with an AI agent. Keep native module versions aligned. For web, install the same-version SDK and React packages together so the exact peer dependency resolves. Install @bugcapsule/web-replay only in replay environments, and @bugcapsule/cli for source-map upload.

Configure credentials and environments

Value	Where it belongs
`bcsdk.v1.…` SDK token	App configuration: the only value an app needs. Client-visible and ingest-only (send Capsules and events, read capture settings); it carries the BugCapsule address, for hosted and self-hosted BugCapsule alike. Generate, rotate and revoke it in the dashboard
Personal or service CLI token	The CLI credential file or CI secrets, never app code or browser environment variables. See CLI install
Project API URL + `bci_…` ingest key	Self-hosted or existing setups (advanced): the explicit alternative to the SDK token in app configuration. Still treated as public
`bcs_…` secret key	Projects without people and roles: CLI and CI only, never in an app

Use one SDK token per app or release channel so you can rotate them separately, and separate QA and production projects when data and settings must be isolated. Web origins include scheme, host and port; ask your team to allow each exact origin. A device's localhost refers to that device, not necessarily your development computer. Keep the app's API and the BugCapsule address distinct.

Upgrade without losing regression coverage

Record the current SDK and CLI versions, app release, source commit and lockfiles.
Read the platform migration notes, update all related modules together, and rebuild. Keep the previous approved artifacts available for rollback.
Run a QA capture, reproduce the failure, verify a fix, and run the existing regression suite. Review a fresh capsule and monitoring event for privacy changes.
Keep semantic action and assertion IDs stable. If checkpoint state changes incompatibly, update stateSchemaVersion; inspect stale regressions and recapture representative flows rather than relabeling them as passing.
Upload symbols from the exact new release build. Deploy that same build, then check event grouping and symbolication before expanding rollout.

Validation scope

The 23 October local release evidence covers all four runtimes' replay/verify/regression paths on Android API 35, an iOS 27 simulator and Chromium. Browser SDK suites also cover Playwright Firefox and WebKit. Native capture files were uploaded using the CLI in that E2E run; it does not prove automatic native delivery on every device.

Remaining gates include physical-device coverage, iOS 15 runtime testing, production performance measurements, source-pinned checkout replay and real dSYM/ELF symbolication end to end. iOS pointer replay and physical-device CLI launch are unimplemented. Playwright WebKit coverage does not certify every Safari/iOS browser. Use the feature matrix to scope adoption.