BagID SDK

The BagID SDK provides a high-level API for airline host applications to manage electronic baggage tags (EBTs) end-to-end: authentication, journey loading, baggage creation, tag transfer over Bluetooth Low Energy (BLE), and tag clearing with custody lock management.

Built with Kotlin Multiplatform, the SDK exposes identical functionality on Android and iOS. On iOS, SKIE bridges Kotlin coroutines and flows to idiomatic Swift constructs.

Core workflow

Diagram

  1. Configure the SDK with API endpoint, client key, token provider, optional theming and localization.

  2. Initialize — the SDK authenticates silently using the host app’s token provider, manages certificates internally.

  3. Load journey from a BCBP barcode or airline-supplied payload.

  4. Create baggage via DCS or airline-provided tag data.

  5. Scan for nearby BagID devices; present the list to the user.

  6. Transfer tag — a single call that handles connect, ownership verification when required, authorization, BLE write, and device attachment.

  7. Clear tag — connect, authorization, clear display, and custody lock removal in one call.

Host app responsibilities

The SDK is headless for most flows: it does not provide journey or scan UI. The host app owns key user flows:

  • Authentication integration: provide a token provider for the SDK to obtain an identity token when needed.

  • Journey & baggage experience: present journey data to the user, guide them through baggage-tagging steps, and surface backend constraints or errors in a user-friendly way.

  • EBT discovery & selection: provide scan and selection UI so the user can choose which EBT to operate on.

  • Custody proof when required: if transferTag fails with custody proof required, collect PNR (recordLocator) and passenger surname and retry with those fields on TransferTagRequest (see TransferTagRequest).

  • Outcome handling: present success/failure outcomes from SDK operations (transfer/clear) to the user.

  • Permissions & state: request platform permissions and guide the user when permissions are unavailable or Bluetooth is off.

The SDK handles HTTP calls, BLE protocols used for supported tags, client certificate issuance for the session, EBT lock/authorize/unlock orchestration for transfer and clear, and merges BLE state into BagIdState.

Capabilities

Journey and baggage operations

  • Load journeys from BCBP barcodes or airline-supplied payloads

  • Create baggage tags via DCS or airline-provided tag data

EBT operations

  • Scan for supported EBT peripherals (scanForEbtTags)

  • Connect and disconnect (connectEbt / disconnectEbt); call notifyDiscoveredModel before connect when the user picks a scan result

  • Optional direct BLE operations (writeEbtTicket, clearEbtDisplay, readEbtBattery, readEbtFirmware) and vendor extras (ebtBleExtras)

  • Transfer a baggage tag to an EBT (transferTag) and clear an EBT (clearTag)

Session and security

  • Federated token authentication via host app token provider

  • Client certificate issued during initialize() for the active session

  • BagIdState merges session flags, device summary, HTTP errors, and BLE transport errors

Design principles

Minimal host app burden

The SDK exposes business-level operations (transferTag, clearTag, loadJourney) and a single BLE façade on BagIdSdk. Protocol details for different tag generations are internal.

Silent setup and auth

The host app provides a token provider. initialize() performs federated login and obtains a client certificate for that session.

Host-owned verification UX

When the backend requires custody proof, the SDK returns a typed error with hints; the host collects PNR and surname and retries transferTag with recordLocator and custodyProofSurname.

Single-session oriented

Connect to one EBT at a time through the façade. Scan, select (notifyDiscoveredModel), connect, operate.

Coroutine-native

Kotlin APIs use suspend functions returning Result<T> where appropriate.

What’s next