Quickstart — iOS (Swift Link SDK)

Launch the hosted bank-connect flow from your iOS app with the 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 iOS deliver it to your app:

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

1. Host https://app.example.com/.well-known/apple-app-site-association:

   { "applinks": { "details": [
     { "appIDs": ["TEAMID.com.example.app"], "components": [{ "/": "/bb-callback*" }] }
   ] } }

2. Add the Associated Domains entitlement: applinks:app.example.com.

Custom scheme (fallback) — acmewallet://bb-callback: add a URL type with scheme acmewallet in your target's Info tab. Custom schemes work without domain setup but any app can claim a scheme — prefer universal links for production.

1. Install

Download bbconnect-swift-0.1.0.zip from the downloads page, unzip it next to your project, and add it in Xcode via File → Add Package Dependencies… → Add Local… (or .package(path: "../bbconnect-swift") in your Package.swift). iOS 13+. An SPM git URL ships 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.connectSessions.create({ returnUrl }) with the API key.
let hostedUrl = try await myBackend.createConnectSession()

3. Launch the flow

import BBConnect

BBConnect.start(
    hostedUrl: hostedUrl,
    callbackURLScheme: "acmewallet"   // custom scheme; use nil for universal links
) { outcome in
    switch outcome {
    case .success(let sessionId, _):
        // The redirect is a UX signal — confirm server-side:
        // your backend polls GET /v1/connect-sessions/{sessionId}.
        showConnected(sessionId)
    case .failure(_, let error):
        showError(error)              // machine-readable reason, e.g. "authentication_failed"
    case .cancelled:
        dismiss()                     // includes the user closing the sheet
    }
}

The SDK opens ASWebAuthenticationSession — never an embedded WKWebView (banks block WebViews; RFC 8252).

4. Universal-link returns

With universal links the return arrives in your app, not the browser session — forward it:

.onOpenURL { url in
    BBConnect.handle(url)
}

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.