Versioning & FAQ

Versioning strategy

The SDK follows semantic versioning:

  • Major — breaking API changes

  • Minor — new functionality, backward compatible

  • Patch — bug fixes, backward compatible

The BLE payload format and UUID values are treated as stable protocol contracts. Changes to these are always a major version bump.

Deprecated symbols are kept for one major version cycle before removal.

For release-by-release notes, see Changelog.

Maintenance checklist

Before releasing a new version:

  1. Validate on a real BagID device: full flow from initialize() through managed TRANSFER and CLEAR (or programmatic transferTag / clearTag).

  2. Verify managed BLE operation list matches ManagedBleFlowRunner (see Managed BLE Operations).

  3. Verify initialize() with the token provider (fresh session after login + client certificate).

  4. Verify custody proof: lock lookup requires verification — Managed BLE Operations or a host CustodyProofCollector collects PNR/surname; rejected proofs retry until max attempts.

  5. Verify TransferResult.pendingRetry handling when attachment fails after a successful BLE write.

  6. Smoke-test GATT v2.0 and v2.1 tags if both are in your certification matrix.

  7. Confirm no coroutine leaks (all launched jobs complete or are cancelled).

  8. Verify ticket payload parity between Android and iOS.

  9. Review logs for PII or device metadata exposure.

  10. Smoke test with Bluetooth off and permission denied.

  11. Verify dependency integration in a clean sample project (Gradle for Android, SPM for iOS).

FAQ

Which managed BLE operations are available?

All operations use the same launch contract (see Managed BLE Operations):

TRANSFER, CLEAR, READ_BATTERY, READ_FIRMWARE, SEND_NAMETAG, HIDE_TICKET, RESTORE_TICKET

Launch via full-screen UI (recommended). Headless runBleOperation is documented under Tag Operations — headless mode.

What is the difference between GATT v2.0 and v2.1 tags?

The SDK infers the generation from BLE advertisements and routes automatically:

  • v2.0 — EbtTagIdentity.BagId — legacy BagID GATT service; simplified BLE authorize path (no SEC handshake).

  • v2.1 — EbtTagIdentity.BagIdBleV21 — newer GATT service with EBT Security (SEC) handshake before writes.

Partner apps call the same APIs (transferTag, managed TRANSFER, clearTag, etc.) regardless of generation. See Transfer & Clear — BLE security for detail.

Why does iOS use a UUID instead of a MAC address for deviceId?

iOS CoreBluetooth does not expose the device’s MAC address. Instead, it assigns a stable UUID per peripheral per iOS device. The SDK abstracts this behind the deviceId: String parameter on both platforms.

Can I connect to multiple devices at once?

The SDK is single-session oriented: scan, select one device, transfer or clear, done. Concurrent connections are not supported.

What EBT types are supported?

Currently only BagID EBTs (BLE transport) are supported. The SDK architecture supports additional EBT types in future versions. Hardware lines include BagID GO and BagID 2 variants (BagIdDeviceType — see EbtTagIdentity).

How do I see SDK debug logs?

The SDK logs via Napier. Your partner app must install a Napier antilog or logs are discarded.

  • Kotlin (Android)

import io.github.aakira.napier.DebugAntilog
import io.github.aakira.napier.Napier

// In Application.onCreate:
Napier.base(DebugAntilog(defaultTag = "BagIdSdk"))

Use a distinct tag (e.g. your app name) and filter Logcat / Xcode console during integration. Avoid shipping verbose debug antilogs in production store builds unless you have a deliberate diagnostics mode.

How does SKIE bridging work on iOS?

SKIE is a Kotlin compiler plugin that generates Swift-friendly wrappers:

  • StateFlow<T> becomes an AsyncSequence — iterate with for await.

  • Flow<T> becomes an AsyncSequence — cold flows start on iteration, cancel on task cancellation.

  • suspend fun f(): Result<T> gets an OrThrow variant: func fOrThrow() async throws → T.

  • Kotlin sealed class subtypes are matched exhaustively with switch onEnum(of:).

Can I theme the managed BLE UI?

Yes. Pass BagIdTheme on BagIdConfig at configure time. Android ManagedBleFlowActivity and iOS BagIdSDKUI read BagIdSdk.configuredTheme for primary, background, text, and error colors. See BagIdTheme and managed BLE UI theming.

BagIdLocalization (locale, string overrides) is available for SDK-owned strings; contact BagID if you need specific override keys for your locale rollout.

What do I do when initialize() returns InitResult.Unavailable?

InitResult.Unavailable carries a reason enum. Use the table below to decide how to respond:

UnavailableReason Root cause Recommended action

TOKEN_PROVIDER_FAILED

Your tokenProvider lambda threw or returned an invalid value.

Check that tokenProvider does not throw for expired sessions — it should silently refresh from your IdP cache. Log the exception and surface a generic "sign in required" message to the user. Do not retry initialize() until the user has re-authenticated.

FEDERATION_REJECTED

BagID backend rejected the token (wrong issuer, expired, wrong audience, or IdP not configured for this environment).

Verify the JWT claims, sourceAppKey, and apiBaseUrl match the target environment. See Debugging FEDERATION_REJECTED for a full checklist. Contact support@bagid.no if the token looks correct.

NETWORK_ERROR

No network or TLS error reaching the BagID API during session setup.

Surface a connectivity error to the user. Retry initialize() after connectivity is restored. Do not retry in a tight loop — wait for a user action or network-availability callback.

Does the SDK handle token refresh automatically?

The SDK stores access and refresh tokens from federated login. Automatic transparent refresh on every HTTP call is not guaranteed in all builds—if the session is invalid, call initialize() again with a working tokenProvider. Consult release notes for your SDK version.

What happens if the network drops after a successful BLE write?

If the attachment HTTP call fails after a successful BLE write, transferTag returns success with TransferResult(bleWriteSuccess = true, attachmentSuccess = false, pendingRetry = true, …​). Managed TRANSFER exposes the same fields in result JSON data. Your partner app can retry transfer or reconcile with the backend according to product rules.

What if custody proof is required during transfer?

For programmatic transferTag or sendNametagTag, the SDK suspends in CustodyProofCollector (or uses BagIdConfig.custodyProofCollector) until valid proof is submitted. Optional recordLocator / custodyProofSurname on TransferTagRequest pre-fill the first attempt.

Managed BLE Operations handles custody inside the SDK surface — no collector required on that path.

Is createAirlineBaggage available?

No in current SDK builds — createAirlineBaggage returns UnsupportedOperationException. Use createBaggageTag (DCS) or see Partner Integration — supported paths.

What happens if the user backgrounds the app during a managed BLE flow?

Platform Behaviour

Android

ManagedBleFlowActivity is an Activity in your task stack. If the user backgrounds the app (Home/Recents) mid-flow, Android preserves the Activity in the back stack. When the user returns, the flow resumes from where it left off. If Android kills the process (low-memory), the Activity is recreated but the in-progress BLE operation is lost — your onActivityResult / Activity Result callback will not be called. In this case BagIdAndroidHost.managedFlowResultJson(data) returns null; treat this as a cancellation and let the user re-launch the flow.

iOS

BagIdIosHost.presentManagedBleFlow presents a UIViewController. iOS suspends CoreBluetooth scans and connections when the app enters the background (unless a background BLE mode is declared). If the BLE operation was not yet complete when backgrounding occurred, the managed flow will fail with a BLE error on foreground return. The completion closure is always called (with a FAILURE or CANCELLED result); handle it the same as a normal failure and allow retry.

For production reliability on iOS, call initialize() and re-obtain a fresh federatedToken each time the user triggers the flow from your UI rather than caching either across backgrounding.

Who do I contact for support?

Reach out to support@bagid.no for integration questions or bug reports. Include SDK version, platform, operation, environment, and result JSON when reporting managed BLE issues (see Partner Integration — support).