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:
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}`);
},
},
});
Fixed an issue on Android where the SDK could crash if DCM configuration cleanup failed. Cleanup errors are now caught and logged, allowing the host app to continue safely.
On iOS the SDK now recovers automatically from a storage key
mismatch without data loss. A stored storage key could become
stale for a number of reasons, leaving the SDK unable to
initialize against existing credential data. This was most
commonly observed during background prewarming, where the SDK
could launch before the device’s first unlock and be unable to
read existing keychain items. On initialization, the SDK now
verifies the active storage key against an on-disk probe and, if
the recorded key is stale, locates the correct key among the
available keychain candidates and repairs the stored reference.
If the probe cannot be read because of filesystem protection,
StorageInitializedInBackground is thrown.
Recovery sequence: the active storage key is verified by attempting to decrypt an encrypted on-disk probe. If the recorded key is stale, the SDK enumerates all available keychain candidates, identifies the one that successfully decrypts the probe, updates the stored key, and removes the stale entry.
None as a
DeviceKeyAuthenticationType option. This allows
credentials to be generated or retrieved with no user
authentication requirement, even when the SDK is initialized with
userAuthenticationBehavior set to
Always or OnDeviceKeyAccess. Pass
{ authenticationPolicy: { type: "None" } }
to retrieveCredentials,
retrieveCredentialsUsingAuthorizationSession, or
generateDeviceKey to opt out of authentication for a
specific device key.
This release fixes the following iOS issues:
nonceEndpoint (when it is advertised in the issuer
metadata) and includes it in the device key proof-of-possession
JWT, improving compliance with the OID4VCI specification.
discoverCredentialOffer would fail when credential
metadata did not include any claims. The claims field
is now treated as optional and defaults to an empty array when
absent.
destroy function did
not fully remove persisted data on iOS devices. It now also
deletes the database encryption key and storage key ID from the
keychain, preventing orphaned keychain entries.
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:
StorageInitializedInBackgroundSdkInitializedInvalidInstanceIDProximityPresentationSessionTerminationErrorType
New 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:
generateDeviceKeyretrieveCredentialsretrieveCredentialsUsingAuthorizationSession
All 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 allowed
UserPresence: 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.
iOS Platform
DiscoveredCredentialOffer on devices running iOS 17.0
or earlier.
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
UserAuthenticationType
iOS 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 parameter
transactionCodeautoTrustMobileIaca 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 struct
The 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 operations
UserAuthenticationBehavior.None no user
authentication is required
UserAuthenticationBehavior.OnDeviceKeyAccess
requires user authentication when presenting or issuing a
credential
UserAuthenticationBehavior.OnInitialise
requires user authentication when initialising the SDK
UserAuthenticationConfiguration.userAuthenticationType
is iOS only and supports the following options:
UserAuthenticationType.BiometricOnly only
biometric authentication is allowed
UserAuthenticationType.BiometricOrPasscode
authentication with either biometrics or device passcode
userAuthRequiredOnInitialise boolean
parameter in the initialise method with
userAuthenticationConfiguration of type
UserAuthenticationConfiguration.
MobileCredentialHolderErrorType.UserAuthenticationOnInitChanged
error type to
MobileCredentialHolderErrorType.UserAuthenticationConfigurationChanged.
CredentialIssuanceOptions to
CredentialIssuanceConfiguration
In 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.CredentialOfferNotFound
DiscoverCredentialOfferErrorType.SupportedCredentialsNotFound
DiscoverCredentialOfferErrorType.CredentialOfferNotInCredentialIssuerMetadata
DiscoverCredentialOfferErrorType.IssuerMetadataServiceError
DiscoverCredentialOfferErrorType.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.AuthCodeNotFound
RetrieveCredentialsErrorTypes.AuthenticationFailed
RetrieveCredentialsErrorTypes.CertificateNotFound
RetrieveCredentialsErrorTypes.DeviceKeyGenerationError
RetrieveCredentialsErrorTypes.GenerateAuthorisationUrlFailed
RetrieveCredentialsErrorTypes.RedirectUriNotFound
RetrieveCredentialsErrorTypes.InvalidTransactionCode
RetrieveCredentialsErrorTypes.WebAuthenticationFailed
RetrieveCredentialsErrorTypes.FailedToDiscoverCredentialOffer
addCredential method can now be used to add
credentials with a future validity period to the storage.
First GA release as a standalone SDK.
Generated using TypeDoc