Developer guide
Integration checklist
Take an integration from its first connection and local capture to a reviewed QA workflow and production rollout.
1. Establish a reproducible baseline
Install the approved artifacts, select the QA project, and record the SDK version, app version/build, source SHA and runtime. Start with one deterministic flow such as checkout. Have a failing assertion ID and a known fix ready.
2. Connect with an SDK token and confirm
- Generate an SDK token for the QA project (Project Settings › Keys › SDK tokens), one per app or release channel. Copy it when it is shown; it can't be shown again. Put it in your build configuration or CI secrets, not in a shared document.
- Initialize with the token-only one-liner for your platform (Flutter, Android, iOS, web). Self-hosted or existing setups may use the explicit address + ingest key form instead.
- Start the app and confirm Configuration fetched in onboarding or the SDK token list, and
connection.stateisconnectedin the SDK's status API. - Send a handled error or trigger a failing
check, then confirm First event or Capsule received. - Try a damaged token in a scratch build and confirm the app still starts, with
invalid_tokenin the status API. Note the log line your team will see. - Read
status.instrumentation.missing. It should be empty by the end of steps 3 and 4.
| Confirmation | Proves | Does not prove |
|---|---|---|
| Configuration fetched | Address, token and network work | That data is captured |
| First event or Capsule received | Captured data reaches the project | That replay is fully instrumented |
3. Initialize before app state is read
Follow your platform's initialization order. Replay must restore storage and registered state before application code consumes them. Add the progressive adapters (network, navigation, app state) as integrations, and register stable semantic actions early. On web, await initialization before rendering; on iOS, use semantic actions because pointer replay is unavailable.
4. Instrument the failing flow
| Concern | Acceptance check |
|---|---|
| Failure | A stable check/fail ID describes the incorrect behavior. Caught errors are reported explicitly. |
| Inputs | Important controls have stable action IDs; text fields are tracked intentionally and sensitive values are excluded. |
| HTTP | Requests pass through the supported integration. Endpoint rules ignore only truly volatile fields; request matching still distinguishes meaningful inputs. |
| Storage/state | Only necessary keys are allowlisted; serializers produce JSON-compatible values and restoration works in a fresh process/context. |
| Time/randomness | Use SDK clock/random hooks where the flow depends on them. Uninstrumented timers and native services can remain nondeterministic. |
5. Inspect before sharing
bugcapsule list
bugcapsule inspect <capsule-id>
bugcapsule inspect <capsule-id> --jsonReplace angle-bracket placeholders. Confirm runtime, source commit, failure assertion, request/response data, storage and eligibility. Review monitoring events separately: inspect is a capsule viewer, not an envelope inspector. Test with synthetic account and payment data, including fields that could leak into messages or URL paths.
6. Prove both the failure and the fix
# Run from the app folder containing bugcapsule.json.
bugcapsule run <capsule-id> -n 3
# Apply the fix to your working tree, then:
bugcapsule verify <capsule-id> -n 5
bugcapsule regress add <capsule-id> --name "checkout rejects negative total"
bugcapsule regress runRequire REPRODUCED before treating a clean fixed build as evidence. Then require FIXED with every requested attempt valid. Revert the fix on a test branch and confirm the regression fails; restore it and confirm it passes. INCONCLUSIVE, timeouts and missing reports are not success. A fix introducing unrecorded network requests needs a new recording covering that path.
7. Exercise delivery and shutdown
Capture offline, restart, reconnect and check eventual delivery. For native crash cases, relaunch the app. Test both capsule and monitoring settings; verify the kill switch stops collection after refresh and clears queued data. Confirm replay builds do not send telemetry and production builds cannot enter replay. Revoke a scratch SDK token and confirm a build that uses it keeps running, stops uploading, and reports rejected with token_revoked. Plan rotation of real tokens with a grace period long enough for the new build to roll out.
8. Handoff and rollout
Give QA the build, flow, expected assertion and capture instructions. Give developers the capsule reference, source SHA, app folder, runtime/device and observed verdict. Add the regression to CI, upload symbols, generate a separate SDK token for production builds, then complete production rollout.
Useful support report
Include SDK/CLI versions, OS/device/browser, app release/commit, exact command and working directory, expected vs actual behavior, verdict and divergence codes, and whether the problem occurs in a clean replay environment. Provide a minimal redacted capsule only through your team's approved channel. Exclude secret keys, full credential files and unnecessary user data. For connection or upload issues, include the SDK's status output (connection.state, reason, message) and a timestamp, never the token itself; for symbolication, include the release and debug ID.