mobile-credential-verifier-react-native

Table of Contents

• Licensing
• Features
• Getting started
• Usage
  • Initialise
  • Trusted issuers
  • Request credentials
  • Error handling

Licensing

Request or download the MATTR Pi SDK Trial Licence Agreement and the MATTR Customer Agreement and review these terms

Features

• Manage trusted issuers
• Request mobile credentials

Getting started

How to get access to MATTR Pi Mobile Credentials Verifier SDK

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.

Install dependencies

Add this SDK as a dependency to the react native app:

yarn add @mattrglobal/mobile-credential-verifier-react-native
Copy

Usage

Initialise

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();
Copy

Trusted issuers

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);
Copy

Request credentials

Request Mobile Credentials:

import {
  createProximityPresentationSession,
  sendProximityPresentationRequest,
  terminateProximityPresentationSession,
} from "@mattrglobal/mobile-credential-verifier-react-native";

// Create new 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;
  // hande 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();
Copy

Error handling

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;
Copy

unwrap

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
}
Copy

Change Log

2.0.0

BREAKING CHANGES

• Refined structure for credential errors in MobileCredentialResponse objects

Features

• Added support for Android platform

Bug Fixes

• Fixed error handler for createProximityPresentationSession and sendProximityPresentationRequest functions
• Fixed createProximityPresentationSession to unregister React Native event listeners on error

Notes

• Dependency upgrades and vulnerability fixes

1.0.1

Notes

• Enhance documentation

[1.0.0]

Features

• Add support for mobile credential (ISO Only). The current functionality includes

  • Manage mobile credential trusted issuer certificates
  • Request mobile credentials from a credential holder device