Initializing the Seam Mobile SDK

1. Install the Seam SDK

The Seam SDK is available for download on request and is fully documented. See the Seam Android and iOS SDK reference documentation.

You must also use the Seam API to perform server-side actions. Consequently, install a Seam server-side SDK in the language of your choice if you have not done so already.

Configure Gradle to use Seam GitHub Packages

This project retrieves the Seam Mobile SDK artifacts from GitHub Packages.

To build successfully, you need valid credentials and must configure Gradle to fetch dependencies from Seam’s private package repository.

Using Kotlin Script (settings.gradle.kts):

settings.gradle.kts

// getPropertyOrNull is a helper function defined in settings.gradle.kts
// to safely read properties from local.properties
fun getPropertyOrNull(propertyName: String): String? {
    val propertiesFile = file("local.properties")
    if (!propertiesFile.exists()) return null

    val properties = Properties()
    properties.load(propertiesFile.inputStream())
    return properties.getProperty(propertyName, null)
}

// settings.gradle.kts
repositories {
    // ... other repositories
    maven {
        name = "GitHubPackages"
        url = uri("https://maven.pkg.github.com/seampkg/seam-mobile-sdk")
        credentials {
            username = getPropertyOrNull("seamUsername")
            password = getPropertyOrNull("seamPat")
        }
    }
}

Using Groovy (settings.gradle):

settings.gradle

// getPropertyOrNull is a helper function defined in settings.gradle
// to safely read properties from local.properties
String getPropertyOrNull(String propertyName) {
    def propertiesFile = file("local.properties")
    if (!propertiesFile.exists()) return null

    def properties = new Properties()
    properties.load(propertiesFile.inputStream())
    return properties.getProperty(propertyName, null)
}

// settings.gradle
repositories {
    // ... other repositories
    maven {
        name = "GitHubPackages"
        url = uri("https://maven.pkg.github.com/seampkg/seam-mobile-sdk")
        credentials {
            username = getPropertyOrNull("githubUsername")
            password = getPropertyOrNull("githubPat")
        }
    }
}

Add your GitHub credentials

Gradle requires two credentials to download the Seam SDK packages from GitHub:

Credential

Description

Where to get it

githubUsername

Your GitHub username.

Use the same username you use to log in to GitHub.

githubPat

Personal Access Token (PAT) with the read:packages scope

Follow the steps below to generate it.

To retrieve your credentials

Ask Seam to add your GitHub account as a collaborator to the private repository: https://github.com/seampkg/seam-mobile-sdk
Once you’ve been added, go to your GitHub account:
Settings → Developer settings → Personal access tokens → Tokens (classic)
Select Generate new token (classic) and choose:
- Expiration: as needed (e.g., 90 days or “No expiration” if permitted)
- Scopes: check only read:packages
Copy the generated token. This is your githubPat value.

Once you have both values, create a local.properties file in your project root:

local.properties

# local.properties (DO NOT COMMIT THIS FILE)
githubUsername=YOUR_GITHUB_USERNAME
githubPat=YOUR_GITHUB_CLASSIC_PAT

Important:

local.properties is listed in .gitignore by default. Never commit this file to version control.
PATs are private credentials--treat them like passwords.
If your token expires or you lose access,

Add Seam SDK dependencies

Include the required Seam SDK components in your app/build.gradle.kts.

The seam-phone-sdk-android-core module provides the core functionality and must be included for all other components to work.

Each additional dependency enables support for a specific lock or credential integration. For example, to use Salto Space, add the seam-phone-sdk-android-saltospace module. You can include as many integration modules as your app requires.

Kotlin script (build.gradle.kts):

app/build.gradle.kts

val seamVersion = "3.1.6" // Or the desired version

dependencies {
    // ... other dependencies
    implementation("co.seam:seam-phone-sdk-android-core:$seamVersion")
    implementation("co.seam:seam-phone-sdk-android-saltoks:$seamVersion")
    implementation("co.seam:seam-phone-sdk-android-saltospace:$seamVersion")
    implementation("co.seam:seam-phone-sdk-android-latch:$seamVersion")
    implementation("co.seam:seam-phone-sdk-android-assaabloy:$seamVersion")
    implementation("co.seam:seam-phone-sdk-android-legic:$seamVersion")
    // ...
}

Groovy script (build.gradle):

app/build.gradle

// app/build.gradle.kts
def seamVersion = "3.1.6" // Or the desired version

dependencies {
    // ... other dependencies
    implementation "co.seam:seam-phone-sdk-android-core:$seamVersion"
    implementation "co.seam:seam-phone-sdk-android-saltoks:$seamVersion"
    implementation "co.seam:seam-phone-sdk-android-saltospace:$seamVersion"
    implementation "co.seam:seam-phone-sdk-android-latch:$seamVersion"
    implementation "co.seam:seam-phone-sdk-android-assaabloy:$seamVersion"
    implementation "co.seam:seam-phone-sdk-android-legic:$seamVersion"
    // ...
}

You can install SeamSDK via CocoaPods or Swift Package Manager (SPM). SeamSDK supports per-lock-provider integration granularity. Include only the modules you need to keep your app footprint minimal.

CocoaPods:

Podfile

use_frameworks!
platform :ios, '15.0'

target 'YourApp' do
  # Local pod install with file path to SeamSdk.podspec
  pod 'SeamSDK', :path => 'PATH_TO_SEAM_SDK/SeamSDK.podspec'
  # Optional subspecs for specific providers:
  pod 'SeamSDK/SeamDormakabaIntegration', :path => 'PATH_TO_SEAM_SDK/SeamSDK.podspec'
  pod 'SeamSDK/SeamLatchIntegration', :path => 'PATH_TO_SEAM_SDK/SeamSDK.podspec'
end

Swift Package Manager:

Package.swift

dependencies: [
    .package(path: "PATH_TO_SEAM_SDK/SeamSDK")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: ["SeamSDK", "SeamSaltoIntegration"]
    )
]

2. Implement any Manufacturer- and Mobile OS-Specific Requirements

Note the following manufacturer- and OS-specific requirements:

Manufacturer-Specific Requirements

See the device or system integration guide for the access control system or device for which you are planning to develop. Further, you may need to register for developer access with the ACS that you have chosen to use.

iOS Requirement

While not required, you can optionally request the com.apple.developer.passkit.pass-presentation-suppression entitlement from the Apple Developer portal. This entitlement prevents Apple Wallet from appearing when scanning for Bluetooth low energy (BLE) or similar locks, improving the unlock experience.

3. Configure a User Identity for your App User and Generate a Client Session Token

A user identity enables the application to request a user's mobile access permissions and use the app to unlock doors.

First, use the Seam API or Seam Console to create a user identity that will correspond to the App User Account using your internal user ID or other identifying information.

Then, using the user identity, create a client session and capture the resulting client session token. This token will be used to authenticate the user on your application.

# Create the user identity.
user_identity = seam.user_identities.create(
    email_address="[email protected]"
)

# Create the client session.
client_session = seam.client_sessions.create(
    user_identity_ids=[user_identity.user_identity_id]
)

# Use this token to launch your mobile controller.
token = client_session.token

# Create the user identity.
user_identity=$(curl -X 'POST' \
  'https://connect.getseam.com/user_identities/create' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
        "email_address": "[email protected]"
  }')
  
# Get the user identity ID.
user_identity_id=$(echo $user_identity | jq -r '.user_identity.user_identity_id')

# Create the client session.
client_session=$(curl -X 'POST' \
  'https://connect.getseam.com/client_sessions/create' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
        \"user_identity_ids\": [\"$user_identity_id\"]
  }")

# Get the resulting client session token and 
# use this token to launch your mobile controller.
token=$(echo $client_session | jq -r '.client_session.token')

// Create the user identity.
const userIdentity = await seam.userIdentities.create({
    email_address: "[email protected]"
});

// Create the client session.
const clientSession = await seam.clientSessions.create({
    user_identity_ids: [userIdentity.user_identity_id]
});

// Use this token to launch your mobile controller.
const token = clientSession.token;

# Create the user identity.
user_identity = client.user_identities.create(
    email_address: "[email protected]"
)

# Create the client session.
client_session = client.client_sessions.create(
    user_identity_ids: [user_identity.user_identity_id]
)

# Use this token to launch your mobile controller.
token = client_session.token

// Create the user identity.
$user_identity = $seam->user_identities->create(
  email_address: "[email protected]"
);

// Create the client session.
$client_session = $seam->client_sessions->create(
  user_identity_ids: [$user_identity->user_identity_id]
);

// Use this token to launch your mobile controller.
$token = $client_session->token;

4. Initialize the Mobile SDK with the Client Session Token

Use the client session token that you generated earlier to bootstrap the Seam SDK on the device. Under the hood, this action sets up credential synchronization and starts a background sync loop to keep permissions up to date.

Initialization and Error Handling

Perform initialization and activation within your app’s asynchronous context (for example, Swift’s Task or Kotlin coroutines) so that you can handle errors. The initialization call may fail due to configuration issues (such as an invalid token), and the activation call may fail due to network or runtime errors. Catch these errors and present a user-friendly message or fallback UI as appropriate.

import SeamSDK

// Initialize the Mobile SDK with the client session token (CST).
Task {
    do {
        // Bootstrap the SDK with the CST from your login flow.
        try Seam.initialize(clientSessionToken: token)
        // Start credential sync and background polling.
        try await Seam.shared.activate()
        print("Seam SDK is now active.")
    } catch let error as SeamError {
        // Handle SDK-specific initialization errors (invalid token, etc).
        showAlert(title: "Initialization Failed", message: error.localizedDescription)
    }
}

try {
    SeamSDK.initialize(context, "seam_cst_...")
    SeamSDK.getInstance().activate()
} 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
        }
    }
}

Credential Errors

Any errors that occur between activation and deactivation surface on individual credential objects through their errors property. You can observe the credentials list to detect and handle these issues in real time.

Observe credential errors

import SeamSDK
import Combine

private var credentialErrorsCancellable: AnyCancellable?

func startMonitoringCredentialErrors() {
    credentialErrorsCancellable = Seam.shared.$credentials
        .sink { credentials in
            for credential in credentials where !credential.errors.isEmpty {
                print("Errors for \(credential.displayName):", credential.errors)
            }
        }
}

Credential error types

awaitingLocalCredential: Waiting for a local credential to become available.
expired: The credential has expired and is no longer valid.
userInteractionRequired(action): User interaction is required to resolve the issue; inspect action for details.
unsupportedDevice: The current device is not supported.
contactSeamSupport: Configuration error requiring developer attention.
unknown: An unclassified or unexpected credential error occurred.

userInteractionRequired actions

completeOtpAuthorization(otpUrl:): The user must complete OTP authorization via the provided URL.
enableInternet: The user must enable internet connectivity.
enableBluetooth: The user must enable Bluetooth on the device.
grantBluetoothPermission: The user must grant Bluetooth permission to the app.
appRestartRequired: The user must restart the app to resolve the issue.

Observe credential errors

// One of the attributes of the credential is a list of errors of type `SeamCredentialError`
coroutineScope.launch {
    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*/ }
    }
}

Credential error types

Loading: The system is waiting for a local credential to become available.
Expired: The credential has expired and is no longer valid.
UserInteractionRequired(val interaction: SeamRequiredUserInteraction): User interaction is required to resolve the issue; check interaction for specifics.
Unknown: An unclassified or unexpected credential error occurred.

userInteractionRequired actions

CompleteOtpAuthorization(val otpUrl: String): The user must complete OTP authorization via the provided URL.
EnableInternet: The user must enable internet connectivity.
EnableBluetooth: The user must enable Bluetooth on the device.
GrantPermissions(val permissions: List<String>): The user must grant the required permissions.
AppRestartRequired: The user must restart the app to resolve the issue.

PreviousIntegrating into Your Mobile Application NextHandling System Permissions

Last updated 25 days ago

Was this helpful?