Quickstart — Android (Kotlin Link SDK)

Launch the hosted bank-connect flow from your Android app with the com.budgetbakers:bbconnect Link SDK. The SDK is pure browser orchestration — your API key never ships in the app; your backend drives the partner API (see the Node/Python quickstarts).

Step 0 — register your return path (do this first)

The hosted flow ends with a redirect to your returnUrl. Register it for your app in the partner portal (Apps → return URLs), then make Android deliver it to your app:

App link (recommended) — https://app.example.com/bb-callback:

1. Host https://app.example.com/.well-known/assetlinks.json:

   [{ "relation": ["delegate_permission/common.handle_all_urls"],
      "target": { "namespace": "android_app",
                  "package_name": "com.example.app",
                  "sha256_cert_fingerprints": ["AB:CD:…"] } }]

2. Add the intent-filter with android:autoVerify="true":

   <intent-filter android:autoVerify="true">
       <action android:name="android.intent.action.VIEW" />
       <category android:name="android.intent.category.DEFAULT" />
       <category android:name="android.intent.category.BROWSABLE" />
       <data android:scheme="https" android:host="app.example.com" android:path="/bb-callback" />
   </intent-filter>

Custom scheme (fallback) — acmewallet://bb-callback: the same intent-filter with android:scheme="acmewallet". Works without domain setup, but any app can claim a scheme — prefer app links for production.

1. Install

Download bbconnect-0.1.0.aar from the downloads page into your app module's libs/ directory:

dependencies {
    implementation(files("libs/bbconnect-0.1.0.aar"))
    // File-based AARs carry no transitive dependencies — add the SDK's
    // single dependency yourself:
    implementation("androidx.browser:browser:1.8.0")
}

minSdk 24. Maven Central coordinates (com.budgetbakers:bbconnect) ship with registry publication — the code won't change.

2. Get a hostedUrl from YOUR backend

// GET https://api.example.com/bb/connect-session  (your endpoint)
// Your backend: scope.connect_sessions.create(return_url) with the API key.
val hostedUrl = myBackend.createConnectSession()

3. Launch the flow and wire the return

import com.budgetbakers.bbconnect.BBConnect
import com.budgetbakers.bbconnect.BBConnectOutcome

BBConnect.start(this, hostedUrl) { outcome ->
    when (outcome) {
        is BBConnectOutcome.Success ->
            // The redirect is a UX signal — confirm server-side:
            // your backend polls GET /v1/connect-sessions/{sessionId}.
            showConnected(outcome.sessionId)
        is BBConnectOutcome.Failure -> showError(outcome.error)
        is BBConnectOutcome.Cancelled -> dismiss()
    }
}

In the activity that owns your return intent-filter (launchMode="singleTop"):

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    intent.data?.let(BBConnect::handle)      // warm return
}

override fun onResume() {
    super.onResume()
    BBConnect.handleResume()                  // closed-tab detection → Cancelled
}

(Cold-start returns: also call intent?.data?.let(BBConnect::handle) in onCreate — see the sample app.)

The SDK opens a Chrome Custom Tab — never an embedded WebView (banks block WebViews; RFC 8252).

Notes

• One flow at a time; exactly one callback per flow.
• hostedUrl and sessionId are opaque — never parse them.
• Sandbox mode shows fictional *_xf banks; the flow is otherwise identical to live.