Merge pull request #714 from seamapi/mobile-v2-updates

medmonds · web-flow · commit ee9e18bad943 · 2025-07-16T11:44:17.000-07:00
Update Mobile SDK Documentation for Android v2 and iOS v3
diff --git a/docs/capability-guides/mobile-access/mobile-device-sdks/handling-system-permissions.md b/docs/capability-guides/mobile-access/mobile-device-sdks/handling-system-permissions.md
@@ -1,103 +1,98 @@
 # Handling System Permissions
 
-This guide demonstrates how to request necessary system permissions, such as Bluetooth or Location Access. The SDK enables your application to identify and request the necessary permissions for specific features. Additionally, it details how to display warnings or banners within your application when required permissions are not enabled.
+The mobile SDK surfaces missing or required system permissions (Bluetooth, internet connectivity, and so on) as `CredentialError.userInteractionRequired(action)` entries in each credential’s `errors` array. After activation, observe these errors and handle the specified actions. Errors update automatically as requirements change.
 
-## Retrieving and Requesting Required Permissions at Start Up
-
-Upon launch, the application needs to request the necessary permissions from the user. To retrieve the obtain the list of required permissions, use the `listRequiredAndroidPermissions` or `listRequiredIosPermissions` methods, and specify the features the application will be using.
+## Monitoring Permission Errors
 
 {% tabs %}
+
 {% tab title="Android Kotlin" %}
 ```kotlin
-val requiredPermissions = seam.phone.native.listRequiredAndroidPermissions(
-  enableUnlockWithTap = true
-)
-
-if (requiredPermissions.isNotEmpty()) {
-  // Request required permissions from the user.
+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)
+                }
+            }
+        }
+    }
 }
 ```
 {% endtab %}
 
 {% tab title="iOS Swift" %}
-```swift
-let requiredPermissions = seam.phone.native.listRequiredIosPermissions( // Coming soon!
-  enableUnlockWithTap: true
-)
 
-if (!requiredPermissions.isEmpty) {
-  // Request required permissions from the user.
+Use Combine to watch the published credentials array and handle permission-related errors:
+
+
+```swift
+import SeamSDK
+import Combine
+
+func startMonitoringPermissionErrors() {
+    permissionCancellable = Seam.shared.$credentials
+        .map { credentials in
+            credentials.flatMap { credential in
+                credential.errors.compactMap { error in
+                    guard case .userInteractionRequired(let action) = error else { return nil }
+                    return action
+                }
+            }
+        }
+        .receive(on: RunLoop.main)
+        .sink { actions in
+            actions.forEach { handlePermissionAction($0) }
+        }
 }
 ```
 {% endtab %}
 {% endtabs %}
 
-Once you've acquired the list of required permissions, please refer to relevant Android and iOS documentation for guidance on adding system permissions.&#x20;
-
-<figure><img src="../../../.gitbook/assets/image (6).png" alt=""><figcaption><p>Requesting Required System Permissions for your App</p></figcaption></figure>
 
-***
+The mobile SDK automatically clears resolved permission errors once the required permission is granted, reflecting the updated credential state.
 
-## Perform a System Check and Display Warnings
+## Handling Permission Actions
 
-An app user may choose to deny the application's permission requests. Before launching any features, your application must perform a system check. If the required permissions are not enabled, the app must inform the user, and instruct the user to enable them.
+Implement your handler for each action:
 
 {% tabs %}
+
 {% tab title="Android Kotlin" %}
 ```kotlin
-fun handleEvent(
-  event: SeamEvent
-) {
-  // Check whether the phone state has changed.
-  // Note that these events are located under the phone namespace.
-  if (event is SeamEvent.Phone) {
-    val phone = seam.phone.get().nativeMetadata
-
-    if (
-      // The desired state has not been met.
-      !phone.canUnlockWithTap
-    ) {
-      if (phone.errors.any { it is SeamError.Phone.Native.MissingRequiredAndroidPermissions }) {
-        // Need to update the required permissions.
-        val requiredPermissions = seam.phone.native.listRequiredAndroidPermissions(
-          enableUnlockWithTap = true
-        )
-
-        // Request the requiredPermissions or prompt the user to do so.
-      }
+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*/ }
     }
-  }
 }
 ```
 {% endtab %}
 
 {% tab title="iOS Swift" %}
 ```swift
-func eventDelegate(
-    event: SeamEvent
-) {
-    // Check whether the phone state has changed.
-    // Note that these events are located under the phone namespace.
-    switch (event) {
-    case .phone: 
-       let phone = seam.phone.get().nativeMetadata // Coming soon!
-       
-       // The desired state has not been met.
-       if(!phone.canUnlockWithTap) {
-         if (phone.errors.contains(where: $0 == {.phone(.native(.missingRequiredIosPermissions)))}) {
-           // Need to update the required permissions.
-           let requiredPermissions = seam.phone.native.listRequiredIosPermissions( // Coming soon!
-             enableUnlockWithTap: true
-           )
-           // Request the requiredPermissions or prompt the user to do so.
-         }
-       }
-       break
+func handlePermissionAction(_ action: CredentialUserAction) {
+    switch action {
+    case .enableInternet:
+        // Prompt the user to enable network connectivity.
+    case .enableBluetooth:
+        // Prompt the user to turn on Bluetooth.
+    case .grantBluetoothPermission:
+        // Prompt the user to grant Bluetooth permission in Settings.
     }
 }
 ```
 {% endtab %}
 {% endtabs %}
 
-<figure><img src="../../../.gitbook/assets/image (7).png" alt=""><figcaption><p>Inform the user to enable required system permissions.</p></figcaption></figure>
 
+## See also
+
+For a complete SwiftUI-based implementation of credential error handling for iOS, see `SeamUnlockCardView` in the SeamComponents library, which demonstrates observing credential errors and updating the UI accordingly.
diff --git a/docs/capability-guides/mobile-access/mobile-device-sdks/initializing-the-seam-mobile-sdk.md b/docs/capability-guides/mobile-access/mobile-device-sdks/initializing-the-seam-mobile-sdk.md
@@ -36,21 +36,39 @@ dependencies {
 {% endtab %}
 
 {% tab title="iOS Swift" %}
-To install the Seam iOS SDK, add the `SeamSdk.podspec` to the `target` block of your [Podfile](https://guides.cocoapods.org/using/using-cocoapods.html).
+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.
 
 {% code title="Podfile" %}
 ```ruby
 use_frameworks!
-
-platform :ios, '...'
+platform :ios, '15.0'
 
 target 'YourApp' do
-  // ...
-  // Local pod install with file path to SeamSdk.podspec
-  pod 'SeamSdk', :path => './SeamSdk.podspec'
+  # 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
 ```
 {% endcode %}
+
+{% tabs %}
+{% tab title="SPM" %}
+```swift
+dependencies: [
+    .package(path: "PATH_TO_SEAM_SDK/SeamSDK")
+],
+targets: [
+    .target(
+        name: "YourApp",
+        dependencies: ["SeamSDK", "SeamSaltoIntegration"]
+    )
+]
+```
+{% endtab %}
+{% endtabs %}
 {% endtab %}
 {% endtabs %}
 
@@ -68,19 +86,15 @@ See the [device or system integration guide](../../../device-and-system-integrat
 
 ### iOS Requirement
 
-If you are developing an iOS app, add [`requestAutomaticPassPresentationSuppression()`](https://developer.apple.com/documentation/passkit/pkpasslibrary/requestautomaticpasspresentationsuppression\(responsehandler:\)) to your app to prevent the user's phone from displaying Apple Wallet while scanning for Bluetooth low energy (BLE) or similar locks. This method suppresses Apple Wallet while your mobile app is in the foreground.
-
-{% hint style="info" %}
-The use of this method requires a special entitlement from Apple.
-{% endhint %}
+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](../managing-mobile-app-user-accounts-with-user-identities.md) enables the application to request a user's mobile access permissions and use the app to unlock doors.
 
-First, use the Seam API to create a [user identity](../managing-mobile-app-user-accounts-with-user-identities.md#what-is-a-user-identity) that will correspond to the App User Account using your internal user ID or other identifying information.
+First, use the Seam API or Seam Console to create a [user identity](../managing-mobile-app-user-accounts-with-user-identities.md#what-is-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](../../../core-concepts/authentication/client-session-tokens/) and capture the resulting [client session token](../../../core-concepts/authentication/client-session-tokens/). This token will be used to authenticate the user on your application.
 
@@ -183,17 +197,20 @@ $client_session = $seam->client_sessions->create(
 $token = $client_session->token;
 ```
 {% endtab %}
+
+
 {% endtabs %}
 
 ***
 
 ## 4. Initialize the Mobile SDK with the Client Session Token
 
-Use the client session token generated earlier to initialize the Seam Mobile SDK. This initializes the Mobile SDK for the app user, and retrieves the relevant provider-specific settings. This also launches a background process that will continually poll for any updates to the access permissions.
 
-### Initialization and Handling Configuration Errors
+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
 
-The initialization process may fail if the Seam workspace or provider-specific settings are not configured properly. If the initialization process encounters any irrecoverable errors, this block will catch these exceptions, specifically those identified as `SeamError`. These errors point to development errors, and should be addressed by making sure that your Workspace and User Identity is configured properly.
+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.
 
 {% tabs %}
 {% tab title="Android Kotlin" %}
@@ -223,94 +240,59 @@ try {
 
 {% tab title="iOS Swift" %}
 ```swift
-import Seam
-
-//  client session token for th user
-let clientSessionToken = 
-
-let seam = SeamClient(
-    clientSessionToken: clientSessionToken,
-    seamEventDelegate: 
-)
-
-try seam.phone.native.initialize(
-    enableUnlockWithTap: true
-)
+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)
+    }
+}
 ```
 {% endtab %}
 {% endtabs %}
 
-### Handling Provider Initialization Errors from the Background Process
-
-Any failures during the background process will produce errors. These errors can be accessed from the error list, and events will also be emitted. To handle these operational errors, you may log the error in logs or displaying a message to the user.
 
-{% tabs %}
-{% tab title="Android Kotlin" %}
-```kotlin
-fun (
-    seam: Seam,
-    event: SeamEvent
-) {
-    // If the event is under the phone namespace, the phone state may have changed.
-    if event is SeamEvent.Phone {
-        val phone = seam.phone.get().nativeMetadata
-    
-        // Check for the desired state of the phone for all app features to work.
-        if (!phone.isInitialized || !phone.canUnlockWithTap) {
-            // Check errors and display them to the user.
-            phone.errors
-            // For example:
-            // SeamError.Phone.Native.MissingRequiredAndroidPermissions: Missing required permissions.
-            // SeamError.Phone.Native.InternetConnectionRequired: No internet.
-            // SeamError.AuthenticationError: Invalid client session token.
-            // SeamError.Internal.Phone.Native.ProviderInitializationFailure: Invalid provider configuration.
-    	    // SeamError.Internal.Phone.Native.ProviderInitializationFailure: Android version not compatible.
-    
-            // Display error message and disable functionality/access, 
-            // until the user resolves the issue.
-        } else {
-          // Set the UI state to indicate that all app features are working.
-        }
-    }
-}
+### Credential Errors
 
-val seam = SeamClient(
-  seamEventHandler = eventHandler,
-  // ...
-)
-```
-{% endtab %}
+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:
 
-{% tab title="iOS Swift" %}
 ```swift
-func (
-    seam: Seam,
-    event: SeamEvent
-) {
-    // If the event is under the phone namespace, the phone state may have changed.
-    switch(event) {
-    case .phone:
-        let phone = seam.phone.get().nativeMetadata // Coming soon!
-        
-        // Check for the desired state of the phone for all app features to work.
-        if (!phone.isInitialized || !phone.canUnlockWithTap) {
-            // check errors and display them to the user.
-            phone.errors
-            // For example:
-            // seam.phone.native.missing_required_ios_permissions: Missing required permissions.
-            // seam.phone.native.internet_connection_required: No internet.
-            // seam.authentication_error: Invalid client session token.
-            // seam.internal.phone.native.provider_initialization_failure: Invalid provider configuration.
-        } else {
-            // Set the UI state to indicate that all app features are working.
+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)
+            }
         }
-    }
 }
-
-let seam = SeamClient(
-  seamEventHandler = eventHandler,
-  // ...
-)
 ```
-{% endtab %}
-{% endtabs %}
+
+#### 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.
diff --git a/docs/capability-guides/mobile-access/mobile-device-sdks/using-unlock-with-tap.md b/docs/capability-guides/mobile-access/mobile-device-sdks/using-unlock-with-tap.md
