Mobile SDK Overview

The Tapkey Mobile SDK enables your partner mobile app to perform local vehicle access flows against the flinkey BLE Box. The backend handles API communication and access decisions; the mobile app handles the customer-facing BLE access experience.

Integration model

flowchart LR
    customer[End customer] --> app[Partner mobile app]
    app --> sdk[Tapkey Mobile SDK]
    sdk --> fBox[flinkey BLE Box]
    app --> backend[Partner backend]
    backend --> api[flinkey API]
    api --> webhook[Partner webhook]
    webhook --> backend
    backend --> appContext[Mobile access context]
    appContext --> app

Responsibility split

Responsibility	Owner
API authentication, customer context, assignments, webhooks	Partner backend
Mobile access context provisioning	Partner backend
Customer-facing access UI	Partner mobile app
Tapkey Mobile SDK integration, BLE communication	Partner mobile app
Access decision (is the customer allowed?)	Partner backend

Danger

The mobile app must never receive API Manager credentials, the flinkey-API-Key, backend bearer tokens or webhook secrets. It receives only the mobile access context needed for the SDK-based access flow.

BLE vehicle access flow

sequenceDiagram
    autonumber
    actor customer as End customer
    participant app as Partner mobile app
    participant backend as Partner backend
    participant sdk as Tapkey Mobile SDK
    participant fBox as flinkey BLE Box

    customer->>app: Start vehicle access
    app->>backend: Request access context
    backend-->>app: Return mobile access context
    app->>sdk: Start access flow
    sdk->>fBox: Discover / connect over BLE
    sdk->>fBox: Authenticate using digital key
    fBox-->>sdk: Authentication result
    sdk-->>app: Access result
    app-->>customer: Show access status

The backend does not need to be online at the exact moment of BLE authentication if the required access context and digital key material are already on the device.

Digital key handling

1. Partner backend creates or updates an assignment.
2. Assignment webhook is received and processed.
3. Partner app requests mobile access context from the backend.
4. Tapkey Mobile SDK enables the local access flow.
5. Driver authenticates locally against the flinkey BLE Box.
6. The BLE Box performs the physical lock/unlock action.

Offline capability

Once a digital key has been synchronized to the device, BLE vehicle access works completely offline — no server contact is required at the moment of unlock or lock. The key remains valid for its configured lifetime (default: 7 days) and the SDK renews it automatically in the background when connectivity is available.

Danger

Do not add online connectivity checks or backend status queries before allowing BLE access. This destroys the offline capability and prevents vehicle access in underground parking, rural areas or during network outages. See Offline Access for details and correct implementation patterns.

Error categories

Category	Example	Handling
Backend access denied	No active assignment	Show clear access-denied message
Missing access context	Backend did not return data	Ask user to retry
Bluetooth disabled	Device BT is off	Ask user to enable Bluetooth
Box not found	No BLE Box in range	Ask user to move closer to vehicle
Local auth failed	Digital key not accepted	Retry once, then escalate
SDK init failed	Misconfigured SDK	Show technical error, log safely
Environment mismatch	UAT/PROD contexts mixed	Stop flow, escalate to support

Platform guides

Tip

Don’t want to build a mobile app yet? Use the pre-built UAT Test App to validate your backend integration and test BLE access immediately.

• Android Integration — Dependencies, authentication, BLE scanning and vehicle access on Android
• iOS Integration — Dependencies, authentication, BLE scanning and vehicle access on iOS

Test checklist

• Partner app can authenticate the customer against the partner backend
• Partner backend can create assignments and receive webhooks
• Partner app can request mobile access context
• Tapkey Mobile SDK is initialized successfully
• App can detect the flinkey BLE Box
• Local BLE access flow succeeds
• Access errors are shown clearly to the customer
• Logs do not contain credentials, tokens or digital keys
• Real-device testing has been completed