Request or download the MATTR Pi SDK Trial License Agreement and the MATTR Customer Agreement and review these terms.
| Technology | Version |
|---|---|
| Xcode | 16.2 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.78.x or higher |
SDK was tested with react-native 0.78.2, and 0.81.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:
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"
+ android:launchMode="singleTask" >
+ <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 8.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
}
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.FailedToDiscoverCredentialOfferTo 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