API Reference

The SDK exposes a single entry point: the BagIdSdk object. All operations are static methods on this object.

The tag operations on BagIdSdk follow a vendor-neutral, layered model (see Tag Operations & Device Types):

  • Core tag operations (transport-agnostic): writeEbtTicket, clearEbtDisplay, readEbtBattery, readEbtFirmware.

  • BLE specialization (device lifecycle): scanForEbtTags, notifyDiscoveredModel, connectEbt, disconnectEbt.

  • BagID implementation (vendor extras, the default and only one today): sendNametagTag / ebtBleExtras, hideEbtTicketDisplay, restoreEbtTicketDisplay, ebtBleDeviceState.

  • Orchestrated flows built on the above: transferTag, clearTag, runBleOperation, and the full-screen managed flow.

You call all of these through the same BagIdSdk façade; the layering describes what each method belongs to, not separate types you wire up.

For production partner integrations, use Managed BLE Operations. Low-level BLE APIs are available for diagnostics, vendor work, and fully custom integrations, but they do not replace managed TRANSFER or CLEAR.

Managed operations

Managed operations are the default EBT surface. The SDK owns BLE permissions, discovery, custody proof, connection handling, backend authorization, tag communication, and result JSON.

Surface Purpose

Android full-screen

BagIdAndroidHost.startManagedBleFlowForResult(…​) launches ManagedBleFlowActivity.

iOS full-screen

BagIdIosHost.presentManagedBleFlow(…​) from BagIdSDKUI.

Headless runBleOperation (same JSON contract, no SDK UI) is documented under Protocol & internals — headless mode.

Supported operation strings: TRANSFER, CLEAR, READ_BATTERY, READ_FIRMWARE, SEND_NAMETAG, HIDE_TICKET, and RESTORE_TICKET.

See Managed BLE Operations for launch parameters, payload JSON, result JSON, custody behavior, and error codes.

BagIdSdk

object BagIdSdk {
    fun configure(config: BagIdConfig)
    suspend fun initialize(): InitResult

    suspend fun loadJourney(request: LoadJourneyRequest): Result<Journey>
    suspend fun createBaggageTag(request: CreateBaggageTagRequest): Result<Journey>
    suspend fun createAirlineBaggage(request: CreateAirlineBaggageRequest): Result<Journey>

    suspend fun runBleOperation(
        operation: String,
        payloadJson: String,
        custodyProofCollector: CustodyProofCollector? = null,
    ): String

    val state: StateFlow<BagIdState>

    // Advanced BLE primitives are listed later on this page.
}

configure

Sets the SDK configuration. Call before initialize.

API Notes

BagIdSdk.configure(BagIdConfig)

Common KMP configuration: API base URL, sourceAppKey, token provider, optional theme/localization.

BagIdSdk.configure(Context, BagIdConfig)

Android extension. Prefer this path so BLE, secure storage, and HTTP setup receive application context.

BagIdSdk.configureWithFederatedToken(…​)

Swift-friendly helper that avoids bridging a suspend token-provider closure.

The empty-token overload configure(apiBaseUrl, sourceAppKey) is a convenience for samples and interop scaffolding. Production integrations should provide a real token provider or federated token.

initialize

initialize() restores any stored session, authenticates with refresh or federated login, and obtains the client certificate used by EBT authorization.

val result: InitResult = BagIdSdk.initialize()

InitResult.Authenticated means journey preparation and managed operations can proceed. InitResult.Unavailable includes an UnavailableReason such as TOKEN_PROVIDER_FAILED, FEDERATION_REJECTED, or NETWORK_ERROR.

Journey preparation

API Purpose

loadJourney(LoadJourneyRequest.Bcbp)

Load a journey from BCBP scan data.

loadJourney(LoadJourneyRequest.AirlinePayload)

Planned partner-supplied journey path. Current builds return UnsupportedOperationException.

createBaggageTag(CreateBaggageTagRequest)

Create or submit baggage through the supported DCS path; returns an updated Journey.

createAirlineBaggage(CreateAirlineBaggageRequest)

Planned partner-issued baggage path. Current builds return UnsupportedOperationException.

See Journey Preparation for examples and current availability.

State

state: StateFlow<BagIdState> exposes the merged SDK session and BLE summary. It is useful for diagnostics, host UI state, and support logging.

val state: StateFlow<BagIdState>

For model fields, see BagIdState.

Product operations for custom integrations

These methods run the product orchestration directly. They are useful when the host owns a custom UI but still wants the SDK to perform backend lock/custody/authorize/attach/unlock work.

transferTag

Runs lock lookup, optional custody proof, EBT authorization, BLE ticket write, and backend device attachment.

suspend fun transferTag(
    request: TransferTagRequest,
    custodyProofCollector: CustodyProofCollector? = null,
): Result<TransferResult>

Prefer managed TRANSFER unless the host owns the full custom UX. Do not replace this with writeEbtTicket; raw BLE write does not update backend attachment.

clearTag

Runs EBT authorization, clears the display over BLE, then unlocks the tag on the backend.

suspend fun clearTag(request: ClearTagRequest): Result<ClearResult>

Prefer managed CLEAR unless the host owns the full custom UX. Do not replace this with clearEbtDisplay; raw BLE clear does not perform backend unlock.

sendNametagTag

Runs lock/custody checks and authorization, then writes the nametag image to a supported BagID tag.

suspend fun sendNametagTag(
    request: SendNametagTagRequest,
    custodyProofCollector: CustodyProofCollector? = null,
): Result<SendNametagResult>

Prefer managed SEND_NAMETAG for partner apps.

Advanced BLE primitives

These APIs expose the BLE layer directly. They are valid for diagnostics, vendor tooling, and fully custom integrations. They are not the recommended partner path and do not perform backend product orchestration by themselves.

API Scope

scanForEbtTags() / scanForEbtTags(deviceId)

Cold Flow<BagIdScanEvent> for BLE discovery.

notifyDiscoveredModel(device)

Records discovery identity before connect.

connectEbt(deviceId) / disconnectEbt()

BLE connection lifecycle.

readEbtBattery() / readEbtFirmware()

Direct BLE readouts.

writeEbtTicket(ticket)

Raw display ticket write to the connected tag. Does not run lock lookup, custody, authorize, or backend attach.

clearEbtDisplay()

Raw display clear command. Does not perform backend unlock.

hideEbtTicketDisplay() / restoreEbtTicketDisplay()

Raw display layer toggles.

ebtBleDeviceState

BLE connection snapshot.

ebtBleExtras(EbtType.BagId)

Vendor-specific raw BLE extras.

hide / restore ticket display

hideEbtTicketDisplay blanks the bag-tag layer so a stored nametag can show. restoreEbtTicketDisplay restores the last bag-tag layer from device memory. Managed operations expose the same behavior as HIDE_TICKET and RESTORE_TICKET.

See Tag Operations & Device Types and Protocol & internals for BLE layering and protocol detail.

Host listeners

BagIdHostListener is an optional callback bridge for hosts that do not want to collect Kotlin flows directly.

interface BagIdHostListener {
    fun onBagIdStateChanged(state: BagIdState)
    fun onEbtBleDeviceStateChanged(ble: EbtBleDeviceState) {}
    fun onAnalyticsEvent(event: String, detail: String? = null) {}
}