Request or download the MATTR Pi SDK Trial License Agreement and the MATTR Customer Agreement and review these terms.
| Technology | Version |
|---|---|
| Xcode | 26 or higher |
| iOS | 15(*) or higher |
| iPhone | iPhone 6S or higher |
| Technology | Version |
|---|---|
| Android Gradle Plugin | 8.3.0 |
| Gradle | 8.3 |
| Kotlin | 1.9.0 |
| JDK | 17 |
| Android min API level | 24 |
| Android target API level | 34 |
| Technology | Version |
|---|---|
| Node | v18 or higher |
| React Native | 0.81.x or higher |
SDK was tested with react-native 0.81.0, and 0.84.0.
Refer to our SDK Docs landing page for step-by-step instructions to gain access to any of our SDKs.
Please reach out in case you need any assistance.
yarn add @mattrglobal/mobile-credential-holder-react-native
Linking the package manually is not required from React Native 0.60 and higher that supports Autolinking.
The SDK relies on the following peer dependencies:
The following mDocs Holder SDK versions are used internally:
Install the pods (via Cocoapods) to complete the linking.
npx pod-install ios
The precompiled MATTR Mobile Credential Holder Android Native SDK is provided in the published NPM package.
To bundle the native libraries, append the following changes to the android/build.gradle script:
allprojects {
repositories {
…
google()
+ maven {
+ url = "$rootDir/../node_modules/@mattrglobal/mobile-credential-holder-react-native/android/frameworks"
+ }
}
}
Add the following activity to your app's android manifest:
<application>
...
+ <activity
+ android:name="global.mattr.mobilecredential.common.webcallback.WebCallbackActivity"
+ android:exported="true"
+ android:label="@string/web_callback_activity_label" >
+ <intent-filter>
+ <action android:name="android.intent.action.VIEW" />
+ <category android:name="android.intent.category.DEFAULT" />
+ <category android:name="android.intent.category.BROWSABLE" />
+ <data android:scheme="${mattrScheme}"
+ android:host="${mattrDomain}" />
+ </intent-filter>
+ </activity>
...
</application>
This configuration allows your Android app to receive authentication results from the browser. The specified values are used to construct the URI that the SDK will use to redirect the user back to your app after they complete authentication with the issuer:
mattrScheme : Can be any path that is handled by your application and registered with the issuer.mattrDomain : Can be any path, however our best practice recommendation is to configure this to be credentials, as
the standard format for the redirect URI is {redirect.scheme}://credentials/callback.The combination of these values ({mattrScheme}://{mattrDomain}/*) must exactly match a redirect URI that has been
whitelisted for the OAuth client used to authenticate the holder. This is required for the SDK to successfully retrieve
credentials.
This SDK can be used in the same application with version 9.0.0 of the React Native mDocs Verifier SDK (
mobile-credential-verifier-react-native).
The SDK distinguishes between expected and unexpected errors to help you write clearer and more predictable code.
Expected errors are part of the normal operation of a function. In these cases, the SDK function will be wrapped in
a Result object from the neverthrow library, with
an explicit error type you can handle programmatically. Some functions do not have expected failure modes. When that’s
the case, their return type will not be wrapped in a Result object. Although this pattern is more verbose, it
encourages the handling of possible errors and reserves throwing exceptions for truly exceptional situations.
Unexpected errors represent bugs, SDK misuse, or system-level failures. In these cases the SDK will throw an exception which results in a rejected promise. Because the root cause is unknown or unrecoverable, we recommend handling them with a generic fallback strategy (e.g., showing an error screen or logging the issue) appropriate to your app’s context.
This separation ensures you know which errors to handle explicitly and which indicate deeper issues that need broader handling.
import {initialize} from "@mattrglobal/mobile-credential-holder-react-native";
const initializeWalletResult = await initialize();
if (initializeWalletResult.isErr()) {
// Handle error from initializeWalletResult.error
return;
}
const wallet = initializeWalletResult.value;
A utility function is provided for convenience if you decide not to handle your errors as results. This function will
simply throw an error if the function passed in returns a Result where Result.isErr() is true.
import {unwrap} from "@mattrglobal/mobile-credential-holder-react-native";
try {
const wallet = unwrap(await initialize());
} catch (error) {
// Handle thrown error
}
If you encounter issues while using the SDK, enabling Native SDK logging can help diagnose problems. You can enable logging during SDK initialization as shown below:
await initialize({
loggerConfiguration: {
logLevel: LogLevel.Verbose,
callbackLogLevel: LogLevel.Verbose,
callback: ({priority, tag, message}) => {
logger.debug(`[${priority}][${tag}]: ${message}`);
},
},
})
This project uses SwiftFormat to enforce consistent Swift code style.
To format Swift code, run the command below inside the directory with the swift files you want to format
swiftformat .
Refer to the SwiftFormat documentation for installation instructions and configuration options.
The SDK now aligns with the finalized OpenID for Verifiable Credential Issuance (OID4VCI) v1.0 specification, upgrading from draft-12.
credentials from discoverCredentialOffer(..)) now includes a mandatory
credentialConfigurationId property.Replaced skipStatusCheck with fetchUpdatedStatusList to improve readability and reduce integration confusion:
true (default): Fetch the latest revocation status list from the server.false: Use cached revocation status (if valid).The initialize method can now return new error types to provide more specific feedback on initialization failures:
StorageInitializedInBackgroundSdkInitializedInvalidInstanceIDProximityPresentationSessionTerminationErrorTypeNew Exception value was added to ProximityPresentationSessionTerminationErrorType. This is a fallback when an
unexpected issue occurs during presentation.
The package path for global.mattr.mobilecredential.common has been updated to global.mattr.mobilecredential.holder.
Please ensure that you update your imports accordingly to avoid any issues with module resolution.
The underlying iOS SDK is built with Xcode 26.0.0. Builds will fail on earlier toolchains (e.g. Xcode 16.4) and CI environments must be upgraded.
Added support for iOS’s Digital Credentials API, as defined in ISO/IEC 18013-7 Annex C (for iOS) and D (for Android). This update allows wallet apps using the Holder SDK to register stored credentials with the system, enabling them to appear in the DC API’s selector UI when a verifier requests credentials.
dcConfiguration parameter has been added to initialize which controls DC API behavior. You can set
different options for iOS and Android.getCurrentLogFile now includes an optional appGroup
parameter. Use appGroup if you want to retrieve logs in the extension. On other platforms, getCurrentLogFile
ignores appGroup.Added support for mDoc Reader authentication as defined in ISO/IEC 18013-5:2021. The SDK can now be used to inspect the verifier authentication result and enable the user to decide whether to share credentials with an unauthenticated verifier.
VerifierAuthenticationResult type which represents the mDoc Reader Authentication result.verifierAuthenticationResult property of type VerifierAuthenticationResult in
MobileCredentialRequest."trusted", "untrusted", or "unsigned" request.VerifierInfo type which represents information regarding the root certificate used to verify the
request.VerifierAuthenticationError which represents the specific authentication error encountered during
verification.VerifierAuthenticationErrorType which represents the string literal that can be returned in the
type field of VerifierAuthenticationError.Device key authentication offers fine-grained control over how each credential is protected and accessed on a user’s device. You can now specify a per-credential authentication policy that defines what user authentication (such as device credentials or biometrics) is required to claim and access a credential.
You can set authentication policy using three methods:
generateDeviceKeyretrieveCredentialsretrieveCredentialsUsingAuthorizationSessionAll three methods generate device keys, with the latter two binding credentials keys. To set authentication policy, use
the authenticationPolicy property as shown below:
const deviceKeyResult = await Holder.generateDeviceKey({
issuer,
audience,
authenticationPolicy: {
type: DeviceKeyAuthenticationType.BiometryCurrentSet,
},
});
generateDeviceKey will store the key with the strictest authentication policy, BiometryCurrentSet. Any access to the
key now requires biometric authentication. It will only allow the current set of biometrics too; changing biometric
settings will invalidate the key.
The four authentication types are as follows, in order of strength:
DeviceCredential: As long as the user has unlocked their phone, they have access to the key. Any authentication
method allowedUserPresence: Requires PIN, fingerprint, etc. on each access to the key. Any authentication method allowed.BiometryAny: Key is accessible only with biometric authentication, but changing or removing biometric settings is
allowed.BiometryCurrentSet: Key is accessible only with the current set of biometrics. Changing or removing a biometric
will invalidate the key.The SDK now supports NFC device engagement for Android devices. This enables starting a proximity presentation session via the NFC channel. A session can now begin when the user taps their device on an NFC-enabled verifier terminal.
The very first step is to add this intent filter to the AndroidManifest.xml of your React Native app:
<intent-filter>
<action android:name="global.mattr.mobilecredential.holder.NFC_RECEIVER_ACTIVITY" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
Then listen for NFC device engagement using setDeviceEngagementListener:
await Holder.setDeviceEngagementListener((error) => {
if (error) {
handleError(error);
return;
}
// no error - can proceed to next step
});
Once the device engagement callback is invoked without error, start the presentation with engagementFromNfc set to
true:
await Holder.createProximityPresentationSession({
...otherOptions,
engagementFromNfc: true,
});
The SDK will invoke the listener upon successful NFC engagement, or if there was an error. If error is undefined,
engagement was successful. The SDK has the device engagement information ready to go. You just need to start the
presentation using engagementFromNfc: true.
Four new methods support NFC presentations:
setDeviceEngagementListener - adds or replace the current listener callback.removeDeviceEngagementListener - removes the listener, if already set.setNfcConfiguration and getNfcConfiguration - update or inspect settings related to NFC.At this time, device engagement works while the app is in the foreground or background. Cold starts (when app is not running) are not currently supported. To start a presentation from NFC, users will first need to open your app, and then scan the verifier NFC's tag.
The SDK now supports the Token Status List Draft 14 specification while maintaining existing support for Draft 3.
application/statuslist+cwt content type header as defined in Section 8.2 of the specification,
while maintaining support for the existing mattr-statuslist+cwt type.Updated COSE algorithms (as per RFC 9864) strengthen cryptographic compatibility and ensure continued compliance with evolving standards.
Android Platform
Branding.name value was not set.iOS Platform
retrieveCredentialsUsingAuthorizationSession would fail on iOS devices running iOS
17.0 or earlier.This enhancement allows applications to implement the OpenID4VCI issuance workflow within embedded WebViews while maintaining full control over the redirect flow.
Applications can now:
createAuthorizationSession method to initiate the flow. This returns an AuthorizationSession object
containing both the authorizeUrl and codeVerifier properties.authorizeUrl in a WebView to handle user authentication and consent.redirectUri, then extract the
authorization code from the returned URL.retrieveCredentialsUsingAuthorizationSession method, passing in
the AuthorizationSession and extracted authorization code.const from enums: UserAuthenticationBehavior and UserAuthenticationTypeiOS Platform
UserAuthenticationType was set to .biometricOrPasscode.addCredential with a credential that could not be verified against any stored trusted
issuer certificate incorrectly threw AddMobileCredentialError.certificateNotFound instead of
AddMobileCredentialError.invalidCredential.Android Platform
retrieveCredentials to hang indefinitely.The following changes reflect the update of the SDK's spelling convention from UK English to US English.
initialise function to initialize.deinitialise function to deinitialize.MobileCredentialHolderError.AuthenticationCancelled to
MobileCredentialHolderError.AuthenticationCanceled.MobileCredentialHolderError.InvalidAuthorisationRequestUri to
MobileCredentialHolderError.InvalidAuthorizationRequestUri.MobileCredentialHolderError.InvalidAuthorisationRequestVerifiedByCertificate to
MobileCredentialHolderError.InvalidAuthorizationRequestVerifiedByCertificate.MobileCredentialHolderError.InvalidAuthorisationRequestVerifiedByDomain to
MobileCredentialHolderError.InvalidAuthorizationRequestVerifiedByDomain.getCredential method was updated as follows:MobileCredentialVerificationFailureType.TrustedIssuerCertificateNotFound
when the credential cannot be verified due to missing a matched trusted issuer certificate.Added a msoHash to the MobileCredential and MobileCredentialMetadata types. This property represents a hashed
mobile security object, defined in ISO/IEC 18013-5:2021. Note that this property is distinct from the id property and
should not be used in the getCredential method.
iOS Platform
IssuerNamespaces field, but according to the Concise Data Definition Language (CDDL) specification defined in
ISO/IEC 18013-5, this field must contain at least one entry. This update enforces that requirement, improving
interoperability and ensuring issued credentials are standards-compliant.The SDK now supports credential claiming using the OID4VCI Pre-Authorized Code Flow. Accordingly, the following changes have been introduced:
Method Signatures:
retrieveCredentials method now accepts:String, instead of the previous CredentialOfferResponse type for the
credentialOffer parametertransactionCodeautoTrustMobileIaca and redirectUri parameters are now set in the initialise method, whereas previously
they were parameters of retrieveCredentials.discoverCredentialOffer and are now managed
interally to the SDK:authorizeEndpoint,tokenEndpoint,credentialEndpoint,mdocIacasUridiscoverCredentialOffer:TransactionCode structThe initialise method now allows configuring how biometric authentication is performed. To allow this the following
changes were introduced:
UserAuthenticationConfiguration object:UserAuthenticationConfiguration.userAuthenticationBehavior supports the following options:UserAuthenticationBehavior.Always requires user authentication for all supported operationsUserAuthenticationBehavior.None no user authentication is requiredUserAuthenticationBehavior.OnDeviceKeyAccess requires user authentication when presenting or issuing a
credentialUserAuthenticationBehavior.OnInitialise requires user authentication when initialising the SDKUserAuthenticationConfiguration.userAuthenticationType is iOS only and supports the following options:UserAuthenticationType.BiometricOnly only biometric authentication is allowedUserAuthenticationType.BiometricOrPasscode authentication with either biometrics or device passcodeuserAuthRequiredOnInitialise boolean parameter in the initialise method with
userAuthenticationConfiguration of type UserAuthenticationConfiguration.MobileCredentialHolderErrorType.UserAuthenticationOnInitChanged error type to
MobileCredentialHolderErrorType.UserAuthenticationConfigurationChanged.CredentialIssuanceOptions to CredentialIssuanceConfigurationIn order to provide a more cohesive and manageable error handling in the OID4VCI flow, we have consolidated some error cases into broader ones. This change aims to make it easier for developers to handle errors consistently. Below is a summary of the changes:
discoverCredentialOffer no longer throws the following errors:DiscoverCredentialOfferErrorType.CredentialOfferNotFoundDiscoverCredentialOfferErrorType.SupportedCredentialsNotFoundDiscoverCredentialOfferErrorType.CredentialOfferNotInCredentialIssuerMetadataDiscoverCredentialOfferErrorType.IssuerMetadataServiceErrorDiscoverCredentialOfferErrorType.FailedToDiscoverCredentialOffer**To see the full list of errors that discoverCredentialOffer may throw, refer to this method in the
SDK documentation.
**
retrieveCredentials no longer throws the following errors:RetrieveCredentialsErrorTypes.AuthCodeNotFoundRetrieveCredentialsErrorTypes.AuthenticationFailedRetrieveCredentialsErrorTypes.CertificateNotFoundRetrieveCredentialsErrorTypes.DeviceKeyGenerationErrorRetrieveCredentialsErrorTypes.GenerateAuthorisationUrlFailedRetrieveCredentialsErrorTypes.RedirectUriNotFoundRetrieveCredentialsErrorTypes.InvalidTransactionCodeRetrieveCredentialsErrorTypes.WebAuthenticationFailedRetrieveCredentialsErrorTypes.FailedToDiscoverCredentialOfferaddCredential method can now be used to add credentials with a
future validity period to the storage.First GA release as a standalone SDK.
Previous versions of this SDK were only available as an extension. For a detailed list of previous changes to this SDK please refer to the React Native Holder SDK changelog under the Mobile Credential category.
Generated using TypeDoc