Connect Your Device

Snapbug supports two connection modes:

  • Chrome Extension room-code pairing: recommended
  • Direct localhost connection: for the desktop app or local service transport

Chrome Extension pairing

This is the default connection flow.

What happens

  1. The Chrome Extension creates a 6-digit room code.
  2. Your app opens Snapbug and enters or scans that code.
  3. The SDK connects through the relay and upgrades to WebRTC when available.
  4. The extension starts receiving live inspector data.

Why this is preferred

  • No ADB commands
  • No port forwarding
  • No need to be on the same network
  • Better onboarding for QA, PM, and support teams

App-side requirements

  • The Snapbug SDK must already be started, for example Snapbug.start(this) on Android.
  • The device must have internet access to reach the relay host.
  • The room code must still be valid when the app submits it.

Connection state

The SDK exposes a connectionState flow (StateFlow<SnapbugConnectionState> on Android) with these states:

  • Disconnected
  • Connecting
  • Connected(viaRelay = ..., viaWebRtc = ...)
  • Error(message = ...)

If the app connects but quickly falls back to Error, the room code may have expired or been entered incorrectly. Room codes expire after about 5 minutes — create a new room in the extension if pairing fails.

Direct localhost connection

Use this when you connect through the local service transport or the desktop app instead of the extension's room-code flow.

This path uses:

  • WebSocket on 9023
  • HTTP uploads on 9024

On Android 9+ you may need a network security config that allows cleartext traffic to localhost and 127.0.0.1.

<application
    android:networkSecurityConfig="@xml/network_security_config" />
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">localhost</domain>
        <domain includeSubdomains="true">127.0.0.1</domain>
    </domain-config>
</network-security-config>

Troubleshooting checklist

  • Recreate the room code if the first attempt fails.
  • Verify the app really initialized Snapbug before trying to connect.
  • Confirm the device can reach the relay.
  • If you are using the direct localhost connection, verify that ports 9023 and 9024 are reachable.
Chrome ExtensionAndroid