Android Bridge SDK

Embed GBG GO identity verification journeys in your Android app using the GBGBridge SDK.

GBGBridge is a lightweight Android library for embedding web-based identity journeys in native apps. It provides a type-safe messaging protocol so web content in an Android WebView can request native capabilities like camera capture, with the same wire protocol as the iOS Bridge SDK.

What GBGBridge enables

• Native capability access from web journeys: Web-based identity flows can request camera capture and other device features through a standardized message protocol.
• Typed capability slots: Declare support for document capture and selfie capture by setting handlers on built-in typed slots. The SDK handles result encoding, busy rejection, and capability query responses automatically.
• Bidirectional messaging: Both the native host and the web content can send and receive structured messages, enabling real-time coordination.
• Capability negotiation with permission state: The web journey can query which native capabilities are available — including camera permission status — before attempting to use them, enabling graceful degradation across environments.
• Works with Compose and the View system: The SDK has no UI dependency. Compose hosts wrap a WebView in AndroidView; View-system hosts attach to a WebView from an Activity or Fragment. Typed slots expose a StateFlow for reactive UI binding.
• Extensible handler architecture: Register custom capability handlers to fulfil any request type the web journey might send, alongside or instead of typed slots.

Architecture at a glance

GBGBridge sits between your Android app and the web journey, routing structured messages in both directions:

The web journey sends structured JSON messages to the native host via window.GBGBridge.postMessage(). The BridgeHost decodes each message, routes requests to registered capability handlers, and sends responses back by evaluating JavaScript on the WebView via window.GBGBridge.receive().

Quick start

The minimum integration is a BridgeHost, a WebView attached to it and pointed at your journey URL, and a handler set on the document-capture slot:

import com.gbg.gbgbridge.core.BridgeHost
import android.webkit.WebView
import androidx.compose.runtime.*
import androidx.compose.ui.viewinterop.AndroidView

@Composable
fun JourneyScreen(journeyUrl: String) {
  val host = remember {
    BridgeHost(hostVersion = "1.0.0").apply {
      // Declare document capture support by setting a handler
      documentCapture.handler = { request ->
        // Present your camera UI and return a result
        documentCapture.awaitCompletion()
      }
    }
  }

  AndroidView(factory = { context ->
    WebView(context).apply {
      host.attach(this)
      loadUrl(journeyUrl)
    }
  })

  DisposableEffect(host) {
    onDispose { host.detach() }
  }
}

Setting a handler on a typed slot automatically declares the capability as supported. attach() handles WebView configuration, bootstrap script injection, and message-channel registration. Capability query responses — including permission state — are built automatically from the slots you configure.

Requirements

Requirement	Minimum
Android	API 24 (Android 7.0)
compileSdk	34
JDK	17
Kotlin	2.x
Distribution	Maven Central (com.gbg:gbgbridge-sdk)
Dependencies	kotlinx-serialization, kotlinx-coroutines, androidx.annotation

Install with a single Gradle dependency:

dependencies {
  implementation("com.gbg:gbgbridge-sdk:0.1.0-alpha01")
}

Reference app

A complete, runnable reference integration — including a companion server, capture screens with CameraX, and terminal-event handling — is available at gbg-go-android-reference. The Tutorial walks through it end to end.

Documentation map

Document	Description
Tutorial	Build a complete Android identity verification app from scratch
Getting Started	Step-by-step installation, setup, and first integration
Concepts	Architecture, mental model, terminology, and design rationale
API Reference	Complete reference for every public type, method, and property
Guides
Embedding	Embedding the WebView in Compose and View-system apps
Messaging	Sending events, handling requests, and response patterns
Capability Handling	Registering handlers, capability queries, and environment negotiation
Capture Screens	Building capture UI with CameraX, the photo picker, and placeholders
Security	Security model, origin allowlisting, and transport safety
Troubleshooting	Common issues, debugging techniques, and diagnostic tools
FAQ	Frequently asked questions
Examples
Hello Journey	Minimal integration — load a journey and display it
Two-Way Communication	Send events and handle requests bidirectionally
Advanced Integration	Custom config, lifecycle handling, error handling, capability checks

License

GBGBridge for Android is published under the MIT license — see the Maven Central listing for distribution details.