GITBOOK-683: Mobile SDK improvements - apple suppression

Author: dawnho

docs/capability-guides/mobile-access/mobile-device-sdks/handling-system-permissions.md

@@ -2,37 +2,61 @@
 
 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.
 
-## Monitoring Permission Errors
+***
+
+## Platform Setup Requirements
+
+First, configure the required platform capabilities.
 
 {% tabs %}
+{% tab title="iOS Swift" %}
+1.  **Suppress Apple Wallet while unlocking with BLE**\
+    To prevent the Apple Wallet dialog from appearing when your app uses BLE to unlock a door, do the following:
+
+    * Add the `requestAutomaticPassPresentationSuppression()` call to your app.\
+      This method suppresses Apple Wallet while your mobile app is in the foreground and ensures a smoother `unlockWithTap` experience.
+    * Request the  `com.apple.developer.passkit.pass-presentation-suppression` entitlement from Apple. 
+
+    Apple Wallet suppression and Bluetooth scanning only apply while the app is in the foreground. Ensure unlock operations are initiated while the app is active.
+2.  **Enable Bluetooth capability**
+
+    Add the required Bluetooth key to your app’s entitlements file:
+
+    ```xml
+    <dict>
+      <key>com.apple.security.device.bluetooth</key>
+      <true/>
+    </dict>
+    ```
+{% endtab %}
+
 {% tab title="Android Kotlin" %}
-```kotlin
-coroutineScope.launch {
-    SeamSDK.getInstance().credentials.collect { credentialsList ->
-        val errors = credentialsList.flatMap { it.errors }
-        errors.forEach { error ->
-            when (error) {
-                is SeamCredentialError.UserInteractionRequired -> {
-                    handleUserInteractionRequired(error.interaction)
-                }
-                else -> { /* handle other errors */ }
-            }
-        }
-    }
+1.  **Request Bluetooth permissions**
 
-    fun handleUserInteractionRequired(interaction: SeamRequiredUserInteraction) {
-        when (interaction) {
-            is SeamRequiredUserInteraction.GrantPermissions -> {
-                 /* handle permissions error */
-                 // interaction.permissions contains the list of required permissions
-            }
-            else -> { /* handle other errors */ }
-        }
-    }
-}
-```
+    Define and call a helper function in your app to request the necessary Bluetooth permissions at runtime.
+2.  **For Android 12 (API 31) and newer:**
+
+    ```
+    Manifest.permission.BLUETOOTH_SCAN
+    Manifest.permission.BLUETOOTH_CONNECT
+    Manifest.permission.BLUETOOTH_ADVERTISE
+    ```
+3.  **For Android 11 (API 30) and older:**
+
+    ```
+    Manifest.permission.BLUETOOTH
+    Manifest.permission.BLUETOOTH_ADMIN
+    Manifest.permission.ACCESS_COARSE_LOCATION
+    Manifest.permission.ACCESS_FINE_LOCATION
+    ```
+
+See [Android request permissions](https://developer.android.com/training/permissions/requesting) for more details.
 {% endtab %}
+{% endtabs %}
+
+## Monitoring Permission Errors
 
+{% tabs %}
 {% tab title="iOS Swift" %}
 Use Combine to watch the published credentials array and handle permission-related errors:
 
@@ -56,10 +80,40 @@ func startMonitoringPermissionErrors() {
         }
 }
 ```
+
+The mobile SDK automatically clears resolved permission errors once the required permission is granted, reflecting the updated credential state.
 {% endtab %}
-{% endtabs %}
+
+{% tab title="Android Kotlin" %}
+```kotlin
+coroutineScope.launch {
+    SeamSDK.getInstance().credentials.collect { credentialsList ->
+        val errors = credentialsList.flatMap { it.errors }
+        errors.forEach { error ->
+            when (error) {
+                is SeamCredentialError.UserInteractionRequired -> {
+                    handleUserInteractionRequired(error.interaction)
+                }
+                else -> { /* handle other errors */ }
+            }
+        }
+    }
+
+    fun handleUserInteractionRequired(interaction: SeamRequiredUserInteraction) {
+        when (interaction) {
+            is SeamRequiredUserInteraction.GrantPermissions -> {
+                 /* handle permissions error */
+                 // interaction.permissions contains the list of required permissions
+            }
+            else -> { /* handle other errors */ }
+        }
+    }
+}
+```
 
 The mobile SDK automatically clears resolved permission errors once the required permission is granted, reflecting the updated credential state.
+{% endtab %}
+{% endtabs %}
 
 ## Handling Permission Actions
 
@@ -95,6 +149,8 @@ func handlePermissionAction(_ action: CredentialUserAction) {
 {% endtab %}
 {% endtabs %}
 
+***
+
 ## 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.

docs/capability-guides/mobile-access/mobile-device-sdks/using-unlock-with-tap.md

@@ -118,6 +118,10 @@ Use Async/Await or Combine to initiate an unlock with a selected credential:
 
 {% tabs %}
 {% tab title="iOS Swift" %}
+{% hint style="info" %}
+If the Apple Wallet dialog appears when using the BLE unlock, see [Handling System Permissions](handling-system-permissions.md#platform-setup-requirements) for steps to prevent it and ensure a smoother unlockWithTap experience.
+{% endhint %}
+
 ```swift
 import SeamSDK
 import Combine
@@ -245,6 +249,8 @@ fun handleCredentialErrors(credentialErrors: List<SeamCredentialError>) {
 {% endtab %}
 {% endtabs %}
 
+***
+
 ## 4. Handle Unlock Events
 
 Handle each `SeamUnlockEvent` to update your UI and logic. Available events: