iOS Verifier SDK v5.0.0 Migration Guide

A guide to help developers migrate from iOS Verifier SDK v4.x to v5.0.0, including breaking changes, new features, and migration steps.

Overview

This guide provides a comprehensive overview of the changes introduced in MobileCredentialVerifierSDK v5.0.0 for iOS, including breaking changes, new features, and migration steps.

Key Features

Lifecycle management improvements: New destroy() method enables complete SDK reset, plus deinitialize() no longer requires @MainActor context for improved flexibility.
Improved reliability in contactless flows: Enhanced BLE performance delivers more consistent proximity credential exchanges and faster engagements.
Enhanced storage reliability: Fixed intermittent storage initialization errors during app launch by migrating key storage from UserDefaults to the Keychain with explicit availability checks.
Better timeout handling: Proximity presentation session timeouts are now correctly propagated to the caller instead of being silently ignored.

For a detailed list of changes included in this release, refer to the SDK Changelog.

Breaking Changes

This section outlines the breaking changes introduced in v5.0.0 that require updates to your existing implementation:

#	Symbol	Change	Impact
1	`MobileCredentialVerifier.sendProximityPresentationRequest(request:skipStatusCheck:)`	Parameter renamed to `checkStatus:` with inverted semantics	All call sites using `skipStatusCheck:` must be updated.
2	`MobileCredentialVerifier.deinitialize()`	No longer `@MainActor`	Can now be called from any actor context.
3	`MobileCredentialVerifierError`	Introduced two new enum cases: `.storageInitializedInBackground`, `.sdkInitialized`	Exhaustive `switch` statements must add new cases.

New Additions

Methods

Method	Purpose
`destroy()`	Destroys SDK instance and deletes all certificates from storage. Throws `sdkInitialized` if called while SDK is initialized.

Enum Cases

Type	New Case	Description
`MobileCredentialVerifierError`	`.storageInitializedInBackground`	SDK initialized without keychain access (e.g., during app prewarming)
`MobileCredentialVerifierError`	`.sdkInitialized`	Operation requires SDK to be deinitialized first

Bug Fixes

Fixed intermittent "unable to initialize storage" errors during app launch. The issue was caused by using UserDefaults for keyId storage, which does not guarantee persistence—particularly during iOS app prewarming when protected data may be unavailable. The SDK now stores the keyId in the Keychain and performs explicit availability checks before initialization, throwing a new storageInitializedInBackground error when the keychain is inaccessible.
Fixed an issue where ProximityPresentationSession timeouts were silently ignored instead of throwing an error. The SDK now correctly propagates timeout errors to the caller when the session times out waiting for a response.

The skipStatusCheck parameter has been renamed to checkStatus with inverted semantics. When checkStatus is true (default), the SDK will verify credential status. When false, it will skip status checking. Update all calls accordingly:

- let response = try await verifier.sendProximityPresentationRequest(request: requests, skipStatusCheck: true)
+ let response = try await verifier.sendProximityPresentationRequest(request: requests, checkStatus: false)

Old Parameter	New Parameter	Mapping
`skipStatusCheck: false` (default)	`checkStatus: true` (default)	No change needed
`skipStatusCheck: true`	`checkStatus: false`	Invert the boolean

Handle new error cases

If you have exhaustive switch statements on MobileCredentialVerifierError, you must add handlers for the two new error cases:

  switch error {
  case .sdkNotInitialized:
      // Handle not initialized
  case .storageInitialization:
      // Handle storage error
+ case .storageInitializedInBackground:
+     // SDK initialized during app prewarming — prompt user to retry
+ case .sdkInitialized:
+     // Operation requires deinitialize() first
  // ... other cases
  }

Error handling guidance:

.storageInitializedInBackground: This error occurs when the SDK is initialized during iOS app prewarming, before the keychain is accessible. Listen for UIApplication.protectedDataDidBecomeAvailableNotification and re-initialize the SDK when keychain access becomes available.
.sdkInitialized: This error is thrown by destroy() when called while the SDK is still initialized. Call deinitialize() first, then retry the operation.

Use `destroy()` for complete reset (optional)

If you need to completely reset SDK state and delete all stored certificates and credentials, you can now call the new destroy() method. This is optional and should be used with caution as it will remove all data:

// Ensure SDK is deinitialized first
await MobileCredentialVerifier.shared.deinitialize()

// Then destroy all stored data
try MobileCredentialVerifier.shared.destroy()

// Re-initialize when needed
try MobileCredentialVerifier.shared.initialize()

Handle `deinitialize()` actor context change

The deinitialize() method is no longer restricted to @MainActor. You can now call it from any context without dispatching to the main actor:

- await MainActor.run {
-     await MobileCredentialVerifier.shared.deinitialize()
- }
+ await MobileCredentialVerifier.shared.deinitialize()

iOS Verifier SDK v5.0.0 Migration Guide

Overview

Key Features

Breaking Changes

New Additions

Methods

Enum Cases

Deprecations

Bug Fixes

Minimum Requirements

Migration Steps

Update `sendProximityPresentationRequest` calls

Handle new error cases

Use `destroy()` for complete reset (optional)

Handle `deinitialize()` actor context change

On this page