SeamSDK - Seam

Auto-generated from the Seam Android SDK Kotlin sources. Do not edit by hand — see codegen/android-reference/.

Overview

class SeamSDK()

This is the main entry point for the Seam Android SDK. Use the getInstance function to get the instance of this class. You can only get the instance of the class after you have initialized the SDK by calling initialize. The initialize function will initialize the SDK.

Thread Safety

All StateFlow properties (credentials, isActivated, unlockStatus) are thread-safe
All suspend functions can be called from any coroutine context
initialize is thread-safe and idempotent

StateFlow Lifecycle

credentials: Emits whenever credential list changes, survives configuration changes
unlockStatus: Emits unlock events, latest event is always available via .value
isActivated: Reflects current SDK activation state

Collecting these flows is lifecycle-safe when used with Android lifecycle-aware scopes

Offline Behavior

SDK caches credentials and can work offline for unlock operations
activate requires internet connection initially
refresh requires internet connection
unlock can work offline if credentials are already cached

Error Recovery

Most operations can be safely retried after fixing underlying issues
Credential errors (in SeamCredential.errors) should be resolved before unlock
Network errors during activate/refresh are transient and can be retried

Background Processing

Unlock operations continue in background
StateFlow emissions work across app lifecycle

Lifecycle

Call initialize once per app session, typically in Application.onCreate()
activate when user wants to use credential features
No explicit cleanup needed - Android handles resource cleanup
deactivate stops background operations but preserves credentials

Companion object methods

`initialize`

Initializes the Seam Android SDK. This should be called once at the start of your application. Example:

try {
    SeamSDK.initialize(context, "seam_cst_...")
} catch (seamError: SeamError) {
    when (seamError) {
        is SeamError.AlreadyInitialized -> {
            // handle error when SDK is already initialized
        }
        is SeamError.DeactivationInProgress -> {
            // handle error when app is being deactivated
        }
        is SeamError.InternetConnectionRequired -> {
            // handle error when internet connection is required
        }
        is SeamError.InvalidClientSessionToken ->  {
            // handle error when client session token is invalid
        }
        else -> {
            // handle other errors
        }
    }
}

suspend fun initialize(context: Context, clientSessionToken: String)

Parameters

Parameter	Description
`context`	the Android context.
`clientSessionToken`	the client session token for the app user.

Throws

SeamError.AlreadyInitialized — if the SDK is already initialized.
SeamError.InternetConnectionRequired — if no internet connection is available.
SeamError.InvalidClientSessionToken — if the token format is invalid.
SeamError.DeactivationInProgress — if a deactivation is in progress.

`getInstance`

Returns the instance of SeamSDK. This can be used to get a handle to the SeamSDK after it has been initialized. This method is thread-safe and can be called from any thread.

fun getInstance() : SeamSDK

Returns — The initialized SeamSDK instance. Throws

SeamError.InitializationRequired — if initialize has not been called yet.

Properties

`isActivated`

Returns whether the app user’s phone has been activated. This StateFlow emits true after successful activate call and false after deactivate. The flow is thread-safe and can be collected from any coroutine context. Latest value is always available via .value property.

val isActivated

`credentials`

Returns the list of SeamCredential for the current app user. This StateFlow emits an immutable list whenever credentials change. The list may be empty if no credentials are available or while loading. Check each credential’s errors property to determine if it’s ready for use. The flow is thread-safe and can be collected from any coroutine context. Latest value is always available via .value property.

// Observe credentials
seamSDK.credentials.collect { credentials ->
    // credentials is a list of [SeamCredential]
    if (credentials.isEmpty()) {
        // handle no credentials
    } else {
        // handle credentials (e.g. display them)
    }
}

// handle credential errors
SeamSDK.getInstance().credentials.collect { credentialsList ->
    val errors = credentialsList.flatMap { it.errors }
    errors.forEach { error ->
        when (error) {
            is SeamCredentialError.Expired -> { /* handle credential expiration error */ }
            is SeamCredentialError.Loading -> { /* handle not loaded yet */ }
            is SeamCredentialError.Unknown -> { /* handle unknown error */ }
            is SeamCredentialError.UserInteractionRequired -> {
                handleUserInteractionRequired(error.interaction)
            }
        }
    }
}

fun handleUserInteractionRequired(interaction: SeamRequiredUserInteraction) {
    when (interaction) {
         is SeamRequiredUserInteraction.CompleteOtpAuthorization -> { /* handle OTP authorization */ }
         is SeamRequiredUserInteraction.EnableBluetooth -> { /* handle Bluetooth error */ }
         is SeamRequiredUserInteraction.EnableInternet -> { /* handle Internet connection error*/ }
         is SeamRequiredUserInteraction.GrantPermissions -> { /* handle permissions error*/ }
    }
}

val credentials

`unlockStatus`

Returns the current status of the unlock feature. This StateFlow emits SeamUnlockEvent instances as unlock operations progress. Events include scanning, connection, access granted, errors, and timeout. The flow retains the latest event, accessible via .value property. Subscribe to this flow before calling unlock to ensure no events are missed. The flow is thread-safe and can be collected from any coroutine context.

val unlockStatus

Methods

`setUnlockEventListener`

Sets the listener for the unlock events.

fun setUnlockEventListener(listener: (SeamUnlockEvent) -> Unit)

Parameters

Parameter	Description
`listener`	the listener to listen for unlock events.

`setNotification`

Sets the notification for the unlock feature. Required for Assa Abloy foreground scanning.

fun setNotification(notification: Notification)

Parameters

Parameter	Description
`notification`	the notification to use for the unlock feature.

`setCredentialsListener`

Sets the listener for the credentials.

fun setCredentialsListener(listener: (List<SeamCredential>) -> Unit)

Parameters

Parameter	Description
`listener`	the listener to listen for credentials.

`listCredentials`

Lists the credentials for the current app user.

fun listCredentials() : List<SeamCredential>

Returns — a SeamResult of a list of AcsPhoneCredential. If the SDK has not been initialized yet, the result will be a SeamFailure with SeamError.InitializationRequired.

`unlock`

Unlocks the app user’s phone. Initiates an unlock operation for the specified credential. Progress events are emitted to unlockStatus StateFlow. The operation continues even if the app goes to background. Works offline if credentials are already cached. Requires the device to have the necessary hardware (Bluetooth, NFC, etc.) and permissions granted.

val seamSDK = SeamSDK.getInstance()
// Start collecting unlock events before unlock
coroutineScope.launch {
    seamSDK.unlockStatus.collect { event ->
        when (event) {
            is SeamUnlockEvent.ScanningStarted -> { /* handle scanning started */ }
            is SeamUnlockEvent.Connecting -> { /* handle connecting */ }
            is SeamUnlockEvent.AccessGranted -> { /* handle access granted */ }
            is SeamUnlockEvent.Timeout -> { /* handle timeout */ }
            is SeamUnlockEvent.ReaderError -> { /* handle reader error */ }
            else -> { /* handle other events */ }
        }
    }
}

// Perform unlock
try {
    val credentialId = credential.id
    // Timeout is optional
    seamSDK.unlock(
        credentialId = credentialId,
        unlockProximity = UnlockProximity.TOUCH,
        timeout = 30.seconds
    )
} catch (seamError: SeamError) {
    when (seamError) {
        is SeamError.ActivationRequired -> {
            // handle error when SDK is not activated
        }
        is SeamError.CredentialErrors -> {
            val credentialErrors = seamError.errors
            handleCredentialErrors(credentialErrors)
            // handle error when there are credential errors
        }
        is SeamError.InitializationRequired -> {
            // handle error when SDK is not initialized
        }
        is SeamError.IntegrationNotFound -> {
            // handle error when integration is not found, Such as Assa Abloy, Latch and Salto
        }
        is SeamError.InvalidCredentialId -> {
            // handle error when credential ID is invalid
        }
        else -> {
            // handle other errors
        }
    }
}

// Handle credential errors on unlock
fun handleCredentialErrors(credentialErrors: List<SeamCredentialError>) {
    credentialErrors.forEach { credentialError ->
        when (credentialError) {
            is SeamCredentialError.Invalid -> {
                // handle error when credential is invalid
            }

            is SeamCredentialError.Expired -> {
                // handle error when credential is expired
            }

            is SeamCredentialError.Loading -> {
                // handle error when credential is not loaded yet
            }

            is SeamCredentialError.UserInteractionRequired -> {
                // handle user interaction required credential error
            }
            is SeamCredentialError.InvalidUnlockProximity -> {
                // handle invalid unlock proximity credential error
            }
            is SeamCredentialError.Unknown -> {
                // handle unknown credential error
            }
        }
    }
}

fun unlock(credentialId: CredentialId, unlockProximity: UnlockProximity? = null, timeout: Duration? = null) : Job

Parameters

Parameter	Description
`credentialId`	the credential ID to unlock. CredentialId is a type alias for String.
`timeout`	the timeout for the unlock operation. If null, uses provider default.
`unlockProximity`	the unlock proximity `UnlockProximity`. If null, uses provider default, which is the first in the list of `SeamCredential.supportedUnlockProximities`. The `SeamCredential` must have at least one supported unlock proximity.

Returns — a Job that can be used to cancel the unlock operation. Throws

SeamError.InitializationRequired — if the SDK has not been initialized yet.
SeamError.IntegrationNotFound — if the integration is not found.
SeamError.InvalidCredentialId — if the credential ID is invalid.
SeamError.ActivationRequired — if the app user’s phone has not been activated yet.
SeamError.CredentialErrors — if the credential has unresolved errors.
SeamError.InvalidUnlockProximity — if the unlock proximity is invalid.

`suspend activate`

Activates the app user’s phone. Prepares the SDK for use by syncing with the server and setting up background services. This operation requires an active internet connection on first activation. Safe to call multiple times - subsequent calls are no-ops if already activated. After successful activation, isActivated will emit true and credentials will start syncing automatically.

val seamSDK = SeamSDK.getInstance()
try {
    // activate is a suspend function
    seamSDK.activate()
} catch (seamError: SeamError) {
    when (seamError) {
        is SeamError.InitializationRequired -> {
            // handle error when SDK is already initialized
        }
        is SeamError.InternetConnectionRequired -> {
            // handle error when internet connection is required
        }
        is SeamError.InvalidClientSessionToken ->  {
            // handle error when client session token is invalid
        }
        else -> {
            // handle other errors
        }
    }
}

suspend fun activate()

Throws

SeamError.InitializationRequired — if the SDK has not been initialized yet.
SeamError.InternetConnectionRequired — if no internet connection is available.
SeamError.InvalidClientSessionToken — if the client session token is invalid.

`suspend deactivate`

Deactivates the app user’s phone. Stops background operations and cleans up resources. Credentials remain cached and available for the next activation. After deactivation, isActivated will emit false. This method is safe to call multiple times and will not throw if already deactivated.

val seamSDK = SeamSDK.getInstance()
try {
    // deactivate is a suspend function
    seamSDK.deactivate(deintegrate = true)
} catch (seamError: SeamError) {
    when (seamError) {
        is SeamError.InitializationRequired -> {
            // handle error when SDK is not initialized
        }
        is SeamError.DeactivationInProgress -> {
            // handle error when internet connection is required
        }
        else -> {
            // handle other errors
        }
    }
}

suspend fun deactivate(deintegrate: Boolean = false)

Parameters

Parameter	Description
`deintegrate`	If true, removes device association and clears all state.

Throws

SeamError.InitializationRequired — if the SDK has not been initialized yet.
SeamError.DeactivationInProgress — if a deactivation is already in progress.

`suspend refresh`

Refreshes the credentials for the current app user. Manually triggers a sync with the server to fetch latest credentials. This operation requires an active internet connection. You should call initialize and activate first. The credentials StateFlow will be updated before this method returns. In most cases, automatic background sync makes manual refresh unnecessary.

val seamSDK = SeamSDK.getInstance()
try {
    seamSDK.refresh()
} catch (seamError: SeamError) {
    when (seamError) {
        is SeamError.InitializationRequired -> {
            // handle error when SDK is not initialized
        }
        is SeamError.DeactivationInProgress -> {
            // handle error when app is being deactivated
        }
        else -> {
            // handle other errors
        }
    }
}

suspend fun refresh() : List<SeamCredential>

Returns — The updated list of credentials after refresh completes. Throws

SeamError.InitializationRequired — if the SDK has not been initialized yet.
SeamError.DeactivationInProgress — if a deactivation is in progress.

​Overview

​Thread Safety

​StateFlow Lifecycle

​Offline Behavior

​Error Recovery

​Background Processing

​Lifecycle

​Companion object methods

​initialize

​getInstance

​Properties

​isActivated

​credentials

​unlockStatus

​Methods

​setUnlockEventListener

​setNotification

​setCredentialsListener

​listCredentials

​unlock

​suspend activate

​suspend deactivate

​suspend refresh

Overview

Thread Safety

StateFlow Lifecycle

Offline Behavior

Error Recovery

Background Processing

Lifecycle

Companion object methods

`initialize`

`getInstance`

Properties

`isActivated`

`credentials`

`unlockStatus`

Methods

`setUnlockEventListener`

`setNotification`

`setCredentialsListener`

`listCredentials`

`unlock`

`suspend activate`

`suspend deactivate`

`suspend refresh`