Request or download the MATTR Pi SDK Trial Licence Agreement and the MATTR Customer Agreement and review these terms.
In this SDK mDocs are referred to as Mobile Credentials.
Refer to our SDK Docs landing page for step-by-step instructions to gain access to any of our SDKs.
Please reach out to us in case you need any assistance Get in touch.
Add this SDK as a dependency to your react native app:
yarn add @mattrglobal/mobile-credential-verifier-react-native
mDocs presentation utilises Bluetooth connection. Make sure the NSBluetoothAlwaysUsageDescription and
NSBluetoothPeripheralUsageDescription descriptions are configured inside Info.plist.
Additional configuration steps are required to bundle the native libraries.
The precompiled MATTR mDocs verifier Android SDK is provided in the published NPM package.
Open the android/build.gradle script and apply the following changes:
allprojects {
repositories {
…
google()
+ maven {
+ url = "$rootDir/../node_modules/@mattrglobal/mobile-credential-verifier-react-native/android/frameworks"
+ }
}
}
Initialise the SDK:
[!NOTE] SDK must be initialised first, otherwise other methods will throw an exception when invoked.
import { initialise } from "@mattrglobal/mobile-credential-verifier-react-native";
await initialise();
The SDK only verifies credentials that were issued by a trusted issuer. The trusted issuer certificates list can be managed directly with the following functions:
Manage trusted issuer certificates
import {
addTrustedIssuerCertificates,
getTrustedIssuerCertificates,
deleteTrustedIssuerCertificate,
} from "@mattrglobal/mobile-credential-verifier-react-native";
// Add a new certificate
const addCertificateResult = await addTrustedIssuerCertificates([
"MIIBwzCCAWmgAwIBAgILAOZSe5t+MOzXtX8wCgYIKoZIzj0EAwIwIDEeMAkGA1UEBhMCTlowEQYDVQQDEwpNQVRUUiBJQUNBMB4XDTIzMDcxODIwMDYzM1oXDTMzMDcxNTIwMDYzM1owIDEeMAkGA1UEBhMCTlowEQYDVQQDEwpNQVRUUiBJQUNBMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0XWwfvFPzbBHiDVLefOueGG1DMHc8WRfXfZqD6748kLZNTOBysm635yM7YCMlkUxDEIHVkLeyV6KoAOM2o0i5qOBiTCBhjASBgNVHRMBAf8ECDAGAQH/AgEDMA4GA1UdDwEB/wQEAwIABjAdBgNVHQ4EFgQUypKEavotsICoAsXypAUUlsVUylMwHAYDVR0SBBUwE4ERaW5mb0BtYXR0ci5nbG9iYWwwIwYDVR0fBBwwGjAYohaGFGh0dHBzOi8vbWF0dHIuZ2xvYmFsMAoGCCqGSM49BAMCA0gAMEUCIClmASfWcf/K2WbClaERQfA38TNTSgYZu2SdNeNFdQyGAiEAhfk+FloZkNOb6TOLcDGqSNwXf+NzvPX0yl+8aq+rMKQ=",
]);
if (addCertificateResult.isErr()) {
const { error } = addCertificateResult;
// handle error scenarios
return;
}
// Get list of all stored certificates
const certificates = await getTrustedIssuerCertificates();
// Delete certificate by id
await deleteTrustedIssuerCertificate(certificateId);
The mDocs verifier supports requesting a credential from a holder device via Bluetooth. The following example shows how you could start a session and request a credential presentation from a holder device:
Only one presentation session is allowed at a time. You must terminate the existing session before starting a new one.
import {
createProximityPresentationSession,
sendProximityPresentationRequest,
terminateProximityPresentationSession,
} from "@mattrglobal/mobile-credential-verifier-react-native";
// start a new presentation session
const createSessionResult = await createProximityPresentationSession({
deviceEngagement: "mdoc:owBjMS4wAYIB2BhYS6QBAiABIVgg_t9K0BaXU27ynODS5q8OcvBZ4m1HFEQwl61lhRD2rdciWCA7hKLr_xN6_bdznDePa_yY1tGdHsc8ni_88uVuehRU-QKBgwIBowD1AfQKUMW8DfgLrUclmxp2InJCddk" // proximity presentation device engagement string
onConnected: () => {
// handle onConnect event
},
onSessionTerminated: () => {
// handle onSessionTerminated event
},
});
if (createSessionResult.isErr()) {
const { error } = createSessionResult;
// handle error scenarios
return;
}
// Send session
const sendRequestResult = await sendProximityPresentationRequest({
mobileCredentialRequests: [{
docType: "org.iso.18013.5.1.mDL",
namespaces: {
"org.iso.18013.5.1": {
family_name: false,
driving_privileges: false,
},
},
}],
});
if (sendRequestResult.isErr()) {
const { error } = sendRequestResult;
// handle error scenarios
return;
}
const response = sendRequestResult.value;
// Terminate current active session
await terminateProximityPresentationSession();
Functions that are expected to have an error path return a
Neverthrow Result type that represents either success
(Ok) or failure (Err).
Although this pattern is more verbose, it encourages the handling of possible errors and reserves throwing exceptions for truly exceptional situations.
import { sendProximityPresentationRequest } from "@mattrglobal/mobile-credential-verifier-react-native";
// Send session
const sendRequestResult = await sendProximityPresentationRequest(...);
if (sendRequestResult.isErr()) {
const { error } = sendRequestResult;
// handle error scenarios
return;
}
const response = sendRequestResult.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, sendProximityPresentationRequest } from "@mattrglobal/mobile-credential-verifier-react-native";
try {
const sendRequestResult = unwrap(await sendProximityPresentationRequest(...));
} catch (error) {
// Handle thrown error
}
The SDK now require peer dependencies of react native 0.73.x.
Realm database has been replaced with a custom storage system. Upgrading to this version will result in all mDocs related data being lost. This includes all trusted issuer certificates and credentials.
The addTrustedIssuerCertificates method error types were updated as follows:
MobileCredentialVerifierErrorType.FailedToStoreCertificate when the given certificate is invalid.MobileCredentialVerifierErrorType.InvalidCertificate.The sendProximityPresentationRequest method error types were updated as follows:
ProximityPresentationSessionErrorType.UnsupportedCurve.ProximityPresentationSessionErrorType.RequestAlreadyInProgress.ProximityPresentationSessionErrorType.MobileCredentialVerificationFailed.The createProximityPresentationSession method error types were updated as follows:
ProximityPresentationSessionErrorType.UnsupportedCurve.Instead of throwing an exception, the sendProximityPresentationRequest method now returns a
MobileCredentialResponse with a credentials[x].verificationResult field to provide a more detailed verification
status (e.g. invalid credential, etc.).
iOS Platform
addTrustedIssuerCertificates can now also accept input in the form of an unformatted PEM string.The createProximityPresentationSession method could return the following errors:
MobileCredentialVerifierErrorType.BluetoothDisabled when Bluetooth is powered off.The sendProximityPresentationRequest method could return the following errors:
MobileCredentialVerifierErrorType.SessionTerminated when the current proximity presentation session is terminated.The onSessionTerminated callback function for createProximityPresentationSession method could be invoked with the
following errors:
ProximityPresentationSessionTerminationError.ResponseNotReceived when mobile credential response not received from
holder.MobileCredentialResponse objectscreateProximityPresentationSession and sendProximityPresentationRequest functionscreateProximityPresentationSession to unregister React Native event listeners on errorAdd support for mobile credential (ISO Only). The current functionality includes
Generated using TypeDoc