Models and State

This page summarizes the models partner apps commonly need for lifecycle, journey preparation, and managed operation payloads. BLE transport models are listed under Advanced BLE models for custom or diagnostic integrations.

Integrator cheat sheet

Concept Type Main use

SDK configuration

BagIdConfig

Configure API URL, sourceAppKey, token provider, optional theme/localization.

Initialization result

InitResult

Decide whether journey and managed operations can proceed.

Journey data

Journey, Passenger, FlightInfo, BaggageRecord, BaggageSlot

Build user screens and managed TRANSFER payloads.

Baggage creation

CreateBaggageTagRequest

Supported DCS baggage path.

Planned airline paths

LoadJourneyRequest.AirlinePayload, CreateAirlineBaggageRequest

Important partner integration direction; current builds expose the shapes but return UnsupportedOperationException.

Managed operation result

JSON string

Parse status, operation, data, code, and message.

SDK state

BagIdState

Observe session status, connected device summary, and last errors.

BagIdConfig

data class BagIdConfig(
    val apiBaseUrl: String,
    val sourceAppKey: String,
    val tokenProvider: suspend () -> String,
    val custodyProofCollector: CustodyProofCollector? = null,
    val maxCustodyProofAttempts: Int = DEFAULT_MAX_CUSTODY_PROOF_ATTEMPTS,
    val theme: BagIdTheme? = null,
    val localization: BagIdLocalization? = null,
)

Use custodyProofCollector for headless or programmatic orchestration (see headless mode and Transfer & Clear). Full-screen managed operations include custody UI inside the SDK surface.

BagIdTheme

data class BagIdTheme(
    val primaryColor: String? = null,
    val backgroundColor: String? = null,
    val textColor: String? = null,
    val errorColor: String? = null,
    val fontFamily: String? = null,
    val borderRadius: Int? = null,
    val inputStyle: InputStyle? = null,
    val buttonStyle: ButtonStyle? = null,
)

Managed BLE UI theming

Android ManagedBleFlowActivity and iOS BagIdSDKUI read BagIdSdk.configuredTheme. Unset values fall back to SDK defaults.

BagIdLocalization

data class BagIdLocalization(
    val locale: String? = null,
    val overrides: Map<String, String>? = null,
)

Localization is reserved alongside theming for host-aligned SDK UI.

InitResult

sealed class InitResult {
    data object Authenticated : InitResult()
    data class Unavailable(val reason: UnavailableReason) : InitResult()
}

enum class UnavailableReason {
    TOKEN_PROVIDER_FAILED,
    FEDERATION_REJECTED,
    NETWORK_ERROR,
}

Journey preparation models

LoadJourneyRequest

sealed class LoadJourneyRequest {
    data class Bcbp(
        val scanData: String,
        val airline: String? = null,
    ) : LoadJourneyRequest()

    data class AirlinePayload(
        val passengers: List<AirlinePassenger>,
    ) : LoadJourneyRequest()
}

Bcbp is the supported journey-load path. AirlinePayload is important for partner-supplied journey data, but current builds return UnsupportedOperationException for that branch.

AirlinePassenger

data class AirlinePassenger(
    val passenger: Passenger,
    val pnr: String,
    val surname: String,
    val flights: List<FlightInfo>,
    val baggage: List<AirlineBaggageInput>? = null,
)

Journey

data class Journey(
    val journeyId: Int,
    val recordLocator: String? = null,
    val passengers: List<Passenger>,
    val flights: List<FlightInfo>,
    val baggage: List<BaggageRecord>,
    val baggageSlots: List<BaggageSlot> = emptyList(),
)

Managed TRANSFER can use a Journey snapshot to build the tag display ticket when displayTicket is not supplied directly.

Passenger

data class Passenger(
    val passengerId: Int? = null,
    val surname: String? = null,
    val givenName: String? = null,
    val title: String? = null,
)

FlightInfo

data class FlightInfo(
    val flightNumber: String,
    val departureAirport: String,
    val destinationAirport: String,
    val departureAt: String?,
)

BaggageRecord

data class BaggageRecord(
    val baggageId: Int,
    val baggageTagNumber: String?,
    val airline: String?,
    val destinationAirport: String?,
    val licensePlate: String? = null,
    val bagTagHumanReadable: String? = null,
)

Use baggageId and journeyId in managed TRANSFER payloads.

CreateBaggageTagRequest

data class CreateBaggageTagRequest(
    val journeyId: Int,
    val passengerList: List<Passenger>,
    val lpn: String? = null,
    val slotNumber: Int? = null,
)

CreateAirlineBaggageRequest

data class CreateAirlineBaggageRequest(
    val journeyId: Int,
    val baggageTagNumber: String,
    val airline: String,
    val destinationAirport: String,
)

This request is part of the planned airline-issued baggage path. Current SDK builds expose the model but createAirlineBaggage returns UnsupportedOperationException.

Managed and product operation models

TransferTagRequest

data class TransferTagRequest(
    val deviceId: String,
    val uniqueDeviceId: String,
    val baggageId: Int,
    val journeyId: Int,
    val recordLocator: String? = null,
    val custodyProofSurname: String? = null,
    val displayTicket: EbtTicket? = null,
    val journey: Journey? = null,
)

Use this only for programmatic custom integrations. Managed TRANSFER uses the JSON equivalent. Provide either displayTicket or a journey containing the selected baggageId.

TransferResult

data class TransferResult(
    val bleWriteSuccess: Boolean,
    val attachmentSuccess: Boolean,
    val pendingRetry: Boolean,
    val device: DeviceInfo,
)

pendingRetry means the BLE write succeeded but backend attachment failed.

ClearTagRequest

data class ClearTagRequest(
    val deviceId: String,
    val uniqueDeviceId: String,
)

ClearResult

data class ClearResult(
    val success: Boolean,
    val unlocked: Boolean,
)

SendNametagTagRequest / SendNametagResult

data class SendNametagTagRequest(
    val deviceId: String,
    val uniqueDeviceId: String,
    val header: String = NAMETAG_IMAGE_HEADER_DEFAULT,
    val imageBytes: ByteArray,
)

data class SendNametagResult(val success: Boolean)

Managed SEND_NAMETAG uses the JSON/base64 equivalent.

CustodyProofCollector

fun interface CustodyProofCollector {
    suspend fun collect(
        hints: CustodyProofHints,
        attempt: Int,
        maxAttempts: Int,
        lastSubmissionError: String?,
    ): CustodyProofInput?
}

Full-screen managed operations provide custody UI. Use this collector for headless or programmatic orchestration — see headless custody helpers and Transfer & Clear.

CustodyProofInput

data class CustodyProofInput(
    val recordLocator: String,
    val surname: String,
)

State models

DeviceInfo

data class DeviceInfo(
    val deviceId: String,
    val serialNumber: String?,
    val batteryLevel: Int?,
    val firmwareVersion: String?,
)

BagIdState

data class BagIdState(
    val authenticated: Boolean,
    val sessionExpired: Boolean,
    val connectedDevice: DeviceInfo?,
    val lastError: String?,
    val bleLastError: String?,
    val identifiedEbtTagIdentity: EbtTagIdentity? = null,
)

lastError covers SDK/API/orchestration failures. bleLastError mirrors the BLE transport.

Advanced BLE models

These models support custom scan/connect flows, diagnostics, and protocol-level integrations. Most partner apps using managed operations do not need them.

BagIdScanEvent

sealed class BagIdScanEvent : ScanEvent {
    data class DeviceFound(val device: DiscoveredEbtBleDevice) : BagIdScanEvent(), ScanEvent.DeviceFound
    data class ScanError(override val message: String) : BagIdScanEvent(), ScanEvent.ScanError
}

scanForEbtTags() returns a cold Kotlin Flow<BagIdScanEvent>.

DiscoveredEbtBleDevice

data class DiscoveredEbtBleDevice(
    val identity: EbtTagIdentity,
    val deviceId: String,
    val signalStrength: Int,
    val advertisedLocalName: String? = null,
)

deviceId is the platform BLE identifier. Use it for connectEbt, not as the backend tag GUID.

EbtTagIdentity

sealed class EbtTagIdentity {
    data class BagId(val model: BagIdDeviceType) : EbtTagIdentity()
    data class BagIdBleV21(val model: BagIdDeviceType) : EbtTagIdentity()
    data class OtherVendor(val modelHint: String?) : EbtTagIdentity()
}

The SDK uses this identity to route to the correct BLE stack. Host apps normally use it only for labels or diagnostics.

BagIdDeviceType

enum class BagIdDeviceType {
    BAGID_GO,
    BAGID_2FM,
    BAGID_2ST,
}

ConnectedEbtDevice

data class ConnectedEbtDevice(
    val uuid: String,
    val deviceId: String,
    val identity: EbtTagIdentity,
    val batteryLevel: Int?,
    val firmwareVersion: FirmwareVersion?,
    val serialNumber: String?,
)

uuid is the stable tag GUID used as managed payload data.uniqueDeviceId when your app stores a registered device.

FirmwareVersion

data class FirmwareVersion(val major: Int, val minor: Int, val revision: Int)

EbtBleDeviceState

data class EbtBleDeviceState(
    val connectedDevice: ConnectedEbtDevice?,
    val lastError: String?,
)

EbtType and vendor BLE extras

sealed class EbtType {
    data object BagId : EbtType()
}

interface EbtBleExtras {
    suspend fun sendNametag(header: String, imageBytes: ByteArray): Result<Unit>
}

ebtBleExtras exposes raw vendor BLE capabilities. Prefer managed SEND_NAMETAG or sendNametagTag for production partner flows.