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.

Android Kotlin

To install the Seam Android SDK:

1. Copy the Seam Android SDK .aar file (for example, seam-phone-sdk-android.aar) into the libs directory for your project.

2. Add the Android Archive (AAR) name (for example, seam-phone-sdk-android) to the dependencies block of the app/build.gradle file for your app.

   There may be additional dependencies required for your specific access control system. For details, see the appropriate system integration guide.

build.gradle.kts

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // ...

    // Add the Seam Android SDK.
    implementation(project(":seam-phone-sdk-android"))
}

iOS Swift

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.

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

SPM

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.

Python

# 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

cURL (bash)

# 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')

JavaScript

// 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;

Ruby

# 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

PHP

// 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.

Android Kotlin

import co.seam.sdk.Seam
import co.seam.sdk.SeamError


// Initialize the Seam client with the client session token. nclude the
// Android activity context and a .
val seam = SeamClient(
    clientSessionToken = seamClientSessionToken,
    androidContext = activityContext,
    seamEventHandler = 
)

try {
    seam.phone.native.initialize(
        // Opt into features with these options
        enableUnlockWithTap = true
    )
} catch (e: SeamError) {
    // Handle unrecoverable initialization errors.
}

iOS Swift

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)
    }
}

Credential Errors

Any errors that occur between activation and deactivation surface on individual credential objects through their errors property. Observe the credentials array to detect and handle these 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: The system is 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 credential issue; check the action for specifics.

• contactSeamSupport: Configuration error requiring developer attention.

• unsupportedDevice: The current device is not supported.

• unknown: An unclassified or unexpected credential error occurred.

Possible 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.