React Native Holder SDK v9.0.0 Migration Guide

Overview

This guide provides a comprehensive overview of the changes introduced in React Native Holder SDK v9.0.0, including breaking changes, new features, and migration steps.

Key Features

• Seamless, OS-native credential presentation (DC API support): The React Native Holder SDK now integrates with the Digital Credentials API on supported platforms (Android devices running Google Play services version 24.0+ and devices running iOS 26 and later), allowing credentials to be presented via an OS overlay without launching your holder app. The OS automatically surfaces only matching credentials across installed holders, reducing friction, avoiding dead ends, and significantly improving the user experience.
• Device key authentication support: The React Native Holder SDK now supports defining a specific authentication method for claiming and accessing specific credentials. This allows you to control how users authenticate. For example, requiring Face ID, fingerprint, or a device passcode, depending on the sensitivity of each credential.
• Verifier Authentication: The Holder SDK now supports Verifier Authentication as defined in ISO/IEC 18013-5:2021. This allows a Holder app to confirm the identity of a verifier when it receives a credential request. This helps improve privacy and trust by allowing you to inform users (or prevent sharing altogether) when a credential is requested by a verifier outside your trusted network. Support for this feature requires implementation in both the Holder and Verifier apps.
• NFC Support (Android Only): The React Native Holder SDK now supports using NFC to start a verification or presentation session on Android devices. This allows users to begin a proximity session by simply tapping two NFC-enabled devices together instead of scanning a QR code.
• Status Lists Draft 14 Support: The SDK now supports the Token Status List Draft 14 specification while maintaining existing support for Draft 3.
• Clearer OID4VCI interoperability (v1.0 alignment): The React Native Holder SDK now aligns with the finalized OID4VCI v1.0 specification (upgraded from draft-12). This alignment improves interoperability across the ecosystem, enabling other systems to clearly identify your supported version and feature set, ensuring smoother integrations and consistent behavior across platforms.
• Stronger cryptography and standards alignment: Updated COSE algorithms (as per RFC 9864) strengthen cryptographic compatibility and ensure continued compliance with evolving standards.
• General stability and performance improvements: Multiple refinements reduce integration friction, increase consistency across mobile environments, and improve overall user experience.

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

Breaking Changes

New Additions

Functions

Updated Function Signatures

• generateDeviceKey(options?) — new optional authenticationPolicy?: DeviceKeyAuthenticationPolicy
• retrieveCredentials(options) — new optional authenticationPolicy?: DeviceKeyAuthenticationPolicy
• retrieveCredentialsUsingAuthorizationSession(options) — new optional authenticationPolicy?: DeviceKeyAuthenticationPolicy
• createProximityPresentationSession(options) — new optional engagementFromNfc?: boolean

New initialize Options

• loggerConfiguration?: LoggerConfiguration — configure SDK logging: logLevel, callbackLogLevel, logDir, callback on log events.
• dcConfiguration?: DCConfiguration — enables Digital Credentials API support:
  • iOS: DCConfigurationIOS (appGroup, supportedDocTypes)
  • Android: DCConfigurationAndroid (enabled: boolean)

New Types & Enums

• Logging:
  • LogLevel
  • LoggerConfiguration
• NFC:
  • NfcConfiguration
  • NfcHandoverMode
  • NfcError
  • NFC Listener type
• Digital Credentials API:
  • DCConfiguration
  • DCConfigurationIOS
  • DCConfigurationAndroid
  • SupportedDocType
• Device Key Authentication:
  • DeviceKeyAuthenticationPolicy
  • DeviceKeyAuthenticationType
  • DeviceKeyAuthenticationInfo
  • DeprecatedDeviceKeyAuthenticationType
• Verifier Authentication:
  • VerifierAuthenticationResult
  • VerifierAuthenticationError
  • VerifierAuthenticationErrorType
  • VerifierInfo

New Error Values

Minimum Requirements

iOS

• iOS 15+ for core SDK functionality
• iOS 26+ for Digital Credentials API (DC API) features

Android

• Android 7 / Nougat / API 24.
• The underlying Android Holder SDK is built using Kotlin 2.0. This adds some intrinsic dependencies into your build tools.
  • Kotlin 2.0 is supported from AGP version 8.5.
  • AGP 8.5 is supported from Gradle version 8.7 and Android Studio Koala 2024.1.1.

Migration Steps

- const credential = await getCredential(id, { skipStatusCheck: true });
+ const credential = await getCredential(id, { fetchUpdatedStatusList: false });

await createProximityPresentationSession({
  // ... other options
  onSessionTerminated: (error: PresentationSessionTerminationError | null) => {
    switch (error?.type) {
      // ... other errors
+     case "Exception":
+       // handle error
+       break;
    }
  },
});

const result = await generateDeviceKey({
  // ... other options
+ authenticationPolicy: {
+   type: DeviceKeyAuthenticationType.BiometryCurrentSet,
+ },
});

const result = await retrieveCredentials( ... );

if (result.isErr()) {
  switch (result.error.type) {
    // ... other errors
+   case "UnsupportedDeviceKeyAuthenticationPolicy":
+     // handle error
+     break;
  }
}

await createProximityPresentationSession({
  // ... other options,
+ engagementFromNfc: true,
});

- <activity android:name="global.mattr.mobilecredential.common.webcallback.WebCallbackActivity">
+ <activity android:name="global.mattr.mobilecredential.holder.webcallback.WebCallbackActivity">
    <!-- ... -->
  </activity>