Learn how to build an application that can verify an mDoc presented via a proximity workflow

• Use the Get Started form to request a trial of MATTR verification capabilities. You will receive access to the following resources:
  • MATTR Pi mDocs Verifier SDK for your chosen platform (iOS, Android, or React Native).
  • MATTR VII tenant.
• As part of your onboarding process you will be provided with access to the following assets:
  • ZIP file which includes the required framework: (MobileCredentialVerifierSDK.xcframework.zip).
  • Sample Verifier app: You can use this app for reference as we work through this tutorial.

• Xcode setup with either:
  • Local build settings if you are developing locally.
  • iOS developer account if you intend to publish your app.

• Verifier device:
  • Supported iOS device to run the built Verifier application on, setup with:
    • Bluetooth access.
    • Available internet connection.
• Holder device:
  • Mobile device with the MATTR GO Hold example app installed and setup with:
    • Biometric authentication.
    • Bluetooth access.
    • Available internet connection.

Step 1: Create a new project

Please follow the detailed instructions to Create a new Xcode Project and add your organization's identifier.

Step 2: Unzip the dependencies file

1. Unzip the MobileCredentialVerifierSDK.xcframework.zip file.
2. Drag the MobileCredentialVerifierSDK.xcframework folder into your project.
3. Configure MobileCredentialVerifierSDK.xcframework to Embed & sign.

See Add existing files and folders for detailed instructions.

This should result in the the following framework being added to your project:

Step 3: Add Bluetooth permissions

The SDK requires access to the mobile device Bluetooth capabilities as part of the proximity presentation workflow. Configure these permissions in the Info tab of the Application target:

Step 4: Run the application

Select Run and make sure the application launches with a “Hello, world!” text in the middle of the display, as shown in the following image:

1. Open the ContentView file in your new project and replace any existing code with the following:

   import SwiftUI
   // Initialize SDK - Step 2.1: Import MobileCredentialVerifierSDK
   
   struct ContentView: View {
       @State var viewModel: VerifierViewModel = VerifierViewModel()
   
       var body: some View {
           NavigationStack(path: $viewModel.navigationPath) {
               VStack {
                   Button("Scan QR Code") {
                       viewModel.navigationPath.append(NavigationState.scanQRCode)
                   }
                   .padding()
   
                   Button("View Response") {
                       viewModel.navigationPath.append(NavigationState.viewResponse)
                   }
                   .padding()
               }
               .navigationDestination(for: NavigationState.self) { destination in
                   switch destination {
                   case .scanQRCode:
                       codeScannerView
                   case .viewResponse:
                       presentationResponseView
                   }
               }
           }
           .task {
               await viewModel.setupCertificates()
           }
       }
   
       // MARK: Verification Views
   
   
       var codeScannerView: some View {
       // Verify mDocs - Step 2.4: Create QRScannerView
           EmptyView()
       }
   
       var presentationResponseView: some View {
       // Verify mDocs - Step 4.2: Create PresentationResponseView
           EmptyView()
       }
   }
   
   // MARK: VerifierViewModel
   
   @Observable
   final class VerifierViewModel {
       var navigationPath = NavigationPath()
       // Initialize SDK - Step 2.2: Add MobileCredentialVerifier var
   
       // Verify mDocs - Step 1.1: Create MobileCredentialRequest instance
   
       // Verify mDocs - Step 1.2: Create receivedDocuments variable
   
       // Initialize SDK - Step 2.3: Initialize the SDK
       
       func setupCertificates() async {
           // Setup certificates - Step 2: Add trusted issuer certificates
           print("This method will add the trust anchor to the sdk storage")
       }
   }
   
   // MARK: Proximity Presentation
   extension VerifierViewModel {
       func setupProximityPresentationSession(_ deviceEngagementString: String) {
       // Verify mDocs - Step 3.2: Create setupProximityPresentationSession
           print("This method will use qr code string do setup proximity session")
       }
       func sendDeviceRequest() {
       // Verify mDocs - Step 3.3: Create sendDeviceRequest function
           print("This method will send preconfigured device request to holder app")
       }
   }
   
   // Verify mDocs - Step 3.1: Extend VerifierViewModel class
   
   
   // MARK: - Navigation
   enum NavigationState: Hashable {
       case scanQRCode
       case viewResponse
   }

1. Add the following code after the // Initialize SDK - Step 2.1: Import MobileCredentialVerifierSDK comment to import MobileCredentialVerifierSDK and gain access to the SDK's capabilities:

   import MobileCredentialVerifierSDK

2. Add the following code after the // Initialize SDK - Step 2.2: Add MobileCredentialVerifier var comment to create a variable that holds the mobileCredentialVerifier instance:

       var mobileCredentialVerifier: MobileCredentialVerifier
       // Holds the asynchronous initialization work so other calls can await it
       // before using the SDK (see Step 2.3).
       private var initializationTask: Task<Void, Error>?

3. Add the following code after the // Initialize SDK - Step 2.3: Initialize the SDK comment to assign a shared instance of the class to our mobileCredentialVerifier variable and initialize the SDK:

       init() {
           mobileCredentialVerifier = MobileCredentialVerifier.shared
           // Keep a handle to the initialization Task so later SDK calls can await it.
           initializationTask = Task {
               do {
                   let platformConfiguration = PlatformConfiguration(
                       tenantHost: Constants.tenantHost,
                       applicationId: Constants.applicationId
                   )
                   try await mobileCredentialVerifier.initialize(platformConfiguration: platformConfiguration)
               } catch let error as MobileCredentialVerifierError {
                   // Print the underlying reason so registration failures are visible.
                   // failedToRegister carries the cause (for example an App Attest
                   // App ID / team mismatch); invalidLicense means no valid license.
                   print("SDK initialization failed:", error)
                   throw error
               }
           }
       }

   The SDK Backend requires a platformConfiguration, so initialize now takes one and is asynchronous (called here from a Task). platformConfiguration contains the following properties, which we will add as constants in the next step:

   • tenantHost: The URL of your MATTR VII tenant where your Verifier Application is configured.
   • applicationId: The id returned when you created the Verifier Application. Network access is required the first time the SDK initializes (for registration) and when the license is later renewed.

4. Create a new file named Constants.swift and add the following, replacing the placeholders with your own values:

   import Foundation
   
   enum Constants {
       static let tenantHost = URL(string: "https://your-tenant.vii.mattr.global")!
       static let applicationId = "<YOUR_VERIFIER_APPLICATION_ID>"
   }

   • tenantHost: The URL of your MATTR VII tenant, available in the MATTR Portal under Platform Management > Tenant.
   • applicationId: The id returned when you created the Verifier Application.

5. Run the app to ensure it compiles successfully.

Once the app launches you will see a screen with three buttons, each leading to an empty view. In the following steps, you will implement proximity presentation functionalities into these views.

1. Create a new file called IACAs.swift and add the following code:

   import Foundation
   
   enum IACAs {
       static let mattrLabs = 
   """
   -----BEGIN CERTIFICATE-----
   MIICYzCCAgmgAwIBAgIKXhjLoCkLWBxREDAKBggqhkjOPQQDAjA4MQswCQYDVQQG
   EwJBVTEpMCcGA1UEAwwgbW9udGNsaWZmLWRtdi5tYXR0cmxhYnMuY29tIElBQ0Ew
   HhcNMjQwMTE4MjMxNDE4WhcNMzQwMTE1MjMxNDE4WjA4MQswCQYDVQQGEwJBVTEp
   MCcGA1UEAwwgbW9udGNsaWZmLWRtdi5tYXR0cmxhYnMuY29tIElBQ0EwWTATBgcq
   hkjOPQIBBggqhkjOPQMBBwNCAASBnqobOh8baMW7mpSZaQMawj6wgM5e5nPd6HXp
   dB8eUVPlCMKribQ7XiiLU96rib/yQLH2k1CUeZmEjxoEi42xo4H6MIH3MBIGA1Ud
   EwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgEGMB0GA1UdDgQWBBRFZwEOI9yq
   232NG+OzNQzFKa/LxDAuBgNVHRIEJzAlhiNodHRwczovL21vbnRjbGlmZi1kbXYu
   bWF0dHJsYWJzLmNvbTCBgQYDVR0fBHoweDB2oHSgcoZwaHR0cHM6Ly9tb250Y2xp
   ZmYtZG12LnZpaS5hdTAxLm1hdHRyLmdsb2JhbC92Mi9jcmVkZW50aWFscy9tb2Jp
   bGUvaWFjYXMvMjk0YmExYmMtOTFhMS00MjJmLThhMTctY2IwODU0NWY0ODYwL2Ny
   bDAKBggqhkjOPQQDAgNIADBFAiAlZYQP95lGzVJfCykhcpCzpQ2LWE/AbjTGkcGI
   SNsu7gIhAJfP54a2hXz4YiQN4qJERlORjyL1Ru9M0/dtQppohFm6
   -----END CERTIFICATE-----
   """.trimmingCharacters(in: .whitespacesAndNewlines)
   }

   This file contains the root certificate of the MATTR Labs test issuer.
2. Return to the ContentView.swift file and replace the print statement under the comment // Setup certificates - Step 2: Add trusted issuer certificates with the following:

      do {
          // Wait for initialization to finish before using the SDK. This returns
          // immediately once initialize has completed, and rethrows if it failed.
          try await initializationTask?.value
          _ = try await mobileCredentialVerifier.addTrustedIssuerCertificates(certificates: [IACAs.mattrLabs])
      } catch {
          print("Failed to add trusted issuer certificate:", error)
      }

This function will be called as soon as the app view appears and the certificate will be added to the app.

Step 1: Create a presentation request

As a verifier, you can select what information you request for verification. Your application implements this by creating a MobileCredentialRequest instance to define the required information, and a new variable to hold the response from the wallet application.

1. Open the ContentView file and add the following code under the // Verify mDocs - Step 1.1: Create MobileCredentialRequest instance comment to define what information to request from the wallet application user:

       let mobileCredentialRequest = MobileCredentialRequest(
           docType: "org.iso.18013.5.1.mDL",
           namespaces: [
               "org.iso.18013.5.1":  [
                   "family_name": false,
                   "given_name": false,
                   "birth_date": false
               ]
           ]
       )

   This object details:

   • The requested credential type (e.g. org.iso.18013.5.1.mDL).
   • The claims required for verification (e.g. family_name).
   • The requested namespace (e.g. org.iso.18013.5.1).
   • Whether or not the verifier intends to persist the claim value (true/false).

   For the verification to be successful, the presented credential must include the referenced claim against the specific namespace defined in the request. Our example requests the birth_date under the org.iso.18013.5.1 namespace. If a wallet responds to this request with a credential that includes a birth_date but rather under the org.iso.18013.5.1.US namespace, the claim will not be verified.

2. Add the following code under the Verify mDocs - Step 1.2: Create receivedDocuments variable comment to create a new receivedDocuments variable that will hold the response from the wallet application:

       var receivedDocuments: [MobileCredentialPresentation] = []

Your application now has an existing credential request to share, and a variable to hold any incoming responses. In the next step we will build the capabilities to send this request and handle the response.

Step 2: Scan and process a QR code

As defined in ISO/IEC 18130-5:2021, a proximity presentation workflow is always initiated by the holder (wallet application user), who must create a QR code for the verifier to scan in order to initiate the device engagement phase.

This means that your verifier application must be able to scan and process this QR code. For ease of implementation, we will use a third party framework to achieve this.

1. Add camera usage permissions to the app target:

2. Add the CodeScanner library via Swift Package Manager.

3. Create a new swift file named QRScannerView and add the following code into it to implement the QR scanning capability:

   import SwiftUI
   import CodeScanner
   import AVFoundation
   
   struct QRScannerView: View {
   
       private let completionHandler: (String) -> Void
   
       init(completion: @escaping (String) -> Void) {
           completionHandler = completion
       }
   
       var body: some View {
           CodeScannerView(codeTypes: [.qr]) { result in
               switch result {
               case .failure(let error):
                   print(error.localizedDescription)
               case .success(let result):
                   print(result.string)
                   completionHandler(result.string)
               }
           }
       }
   }

4. Back in the ContentView file, replace the EmptyView() under the // Verify mDocs - Step 2.4: Create QRScannerView comment with the following code to create a new app view that the user will use to scan a QR code:

       QRScannerView(
           completion: { string in
               viewModel.setupProximityPresentationSession(string)
           }
       )

5. Run the app and select the Scan QR Code button. You should be navigated to the new QRScannerView where you can use the camera to scan a QR code.

Next we will build the logic that handles this QR code to establish a secure connection with the wallet application.

Step 3: Exchange presentation request and response

1. Add the following code under the Verify mDocs - Step 3.1: Extend VerifierViewModel class to extend the VerifierViewModel class with the ProximityPresentationSessionListener protocol:

   extension VerifierViewModel: ProximityPresentationSessionListener {
   
               public func onEstablished() {
                   sendDeviceRequest()
               }
   
               // Session-creation failures (Bluetooth permission, transport setup,
               // unsupported curve, and so on) are delivered here, not to onTerminated.
               // onError has an empty default implementation, so without this method
               // those failures would be silent.
               public func onError(error: (any Error)?) {
                   print("Proximity session error:", error?.localizedDescription ?? "unknown")
               }
   
               public func onTerminated(error: (any Error)?) {
                   print("Session terminated:", error?.localizedDescription ?? "none")
               }
           }

   Now, as soon as a connection is established, the app will send a device request. You will implement the functionality of sendDeviceRequest() in VerifierViewModel later in the tutorial. If a session cannot be created, onError reports the reason.

2. Replace the print statement under the // Verify mDocs - Step 3.2: Create setupProximityPresentationSession comment with the following code to call the SDK's createProximityPresentationSession function, passing a device engagement string (retrieved from a QR code) and self as a listener to create a proximity presentation session:

    mobileCredentialVerifier.createProximityPresentationSession(encodedDeviceEngagementString: deviceEngagementString, listener: self)

3. Replace the print statement under the // Verify mDocs - Step 3.3: Create sendDeviceRequest function comment with following code to implement the logic to send a device request:

       Task { @MainActor in
           receivedDocuments = []
           do {
               // Navigate to response screen
               navigationPath.append(NavigationState.viewResponse)
               // Request mDocs
               let deviceResponse = try await mobileCredentialVerifier.sendProximityPresentationRequest(
                   request: [mobileCredentialRequest]
               )
   
               // Assign new values from the response
               receivedDocuments = deviceResponse.credentials
               // Terminate session after response is received (optional)
               await mobileCredentialVerifier.terminateProximityPresentationSession()
           } catch {
               print(error)
               receivedDocuments = []
           }
       }

   This function now implements the following logic:

   1. Navigate to the viewResponse screen.
   2. Send a proximity presentation request using the SDK's requestMobileCredentials function.
   3. Store the wallet response in the deviceResponse variable. This includes the verification results of any credentials included in the response.
   4. Store the verification results in the receivedDocuments variable.
   5. Terminate the presentation session once the response is received.

Step 4: Display verification results

1. Create a new file named DocumentView and add the following code to display available verification results:

   import MobileCredentialVerifierSDK
   import SwiftUI
   
       struct DocumentView: View {
   
           var viewModel: DocumentViewModel
   
           var body: some View {
               VStack(alignment: .leading, spacing: 10) {
                   Text(viewModel.docType)
                       .font(.title)
                       .fontWeight(.bold)
                       .padding(.bottom, 5)
   
                   Text(viewModel.verificationResult)
                       .font(.title)
                       .fontWeight(.bold)
                       .foregroundStyle(viewModel.verificationFailedReason == nil ? .green : .red)
                       .padding(.bottom, 5)
   
                   if let verificationFailedReason = viewModel.verificationFailedReason {
                       Text(verificationFailedReason)
                           .font(.title3)
                           .fontWeight(.bold)
                           .foregroundStyle(.red)
                           .padding(.bottom, 5)
                   }
   
                   ForEach(viewModel.namespacesAndClaims.keys.sorted(), id: \.self) { key in
                       VStack(alignment: .leading, spacing: 5) {
                           Text(key)
                               .font(.headline)
                               .padding(.vertical, 5)
                               .padding(.horizontal, 10)
                               .background(Color.gray.opacity(0.2))
                               .cornerRadius(5)
   
                           ForEach(viewModel.namespacesAndClaims[key]!.keys.sorted(), id: \.self) { claim in
                               HStack {
                                   Text(claim)
                                       .fontWeight(.semibold)
                                   Spacer()
                                   Text(viewModel.namespacesAndClaims[key]![claim]! ?? "")
                                       .fontWeight(.regular)
                               }
                               .padding(.vertical, 5)
                               .padding(.horizontal, 10)
                               .background(Color.white)
                               .cornerRadius(5)
                               .shadow(radius: 1)
                           }
                       }
                       .padding(.vertical, 5)
                   }
   
                   if !viewModel.claimErrors.isEmpty {
                   Text("Failed Claims:")
                       .font(.headline)
                       .padding(.vertical, 5)
   
                       ForEach(viewModel.claimErrors.keys.sorted(), id: \.self) { key in
                           VStack(alignment: .leading, spacing: 5) {
                               Text(key)
                                   .font(.headline)
                                   .padding(.vertical, 5)
                                   .padding(.horizontal, 10)
                                   .background(Color.gray.opacity(0.2))
                                   .cornerRadius(5)
   
                               ForEach(viewModel.claimErrors[key]!.keys.sorted(), id: \.self) { claim in
                                   HStack {
                                       Text(claim)
                                           .fontWeight(.semibold)
                                       Spacer()
                                       Text(viewModel.claimErrors[key]![claim]! ?? "")
                                           .fontWeight(.regular)
                                   }
                                   .padding(.vertical, 5)
                                   .padding(.horizontal, 10)
                                   .background(Color.white)
                                   .cornerRadius(5)
                                   .shadow(radius: 1)
                               }
                           }
                           .padding(.vertical, 5)
                       }
                   }
               }
               .padding()
               .background(RoundedRectangle(cornerRadius: 10).fill(Color.white).shadow(radius: 5))
               .padding(.horizontal)
           }
       }
   
       // MARK: DocumentViewModel
   
       @Observable
       class DocumentViewModel {
           let docType: String
           let namespacesAndClaims: [String: [String: String?]]
           let claimErrors: [String: [String: String?]]
           let verificationResult: String
           let verificationFailedReason: String?
   
           init(from presentation: MobileCredentialPresentation) {
               self.docType = presentation.docType
               self.verificationResult = presentation.verificationResult.verified ? "Verified" : "Invalid"
               self.verificationFailedReason = presentation.verificationResult.failureType?.rawValue
   
               self.namespacesAndClaims = presentation.claims?.reduce(into: [String: [String: String]]()) { result, outerElement in
                   let (outerKey, innerDict) = outerElement
                   result[outerKey] = innerDict.mapValues { $0.textRepresentation }
               } ?? [:]
   
               self.claimErrors = presentation.claimErrors?.reduce(into: [String: [String: String]]()) { result, outerElement in
                   let (outerKey, innerDict) = outerElement
                   result[outerKey] = innerDict.mapValues { "\($0)" }
               } ?? [:]
           }
       }
   
       // MARK: Helper
       extension MobileCredentialElementValue {
           var textRepresentation: String {
               switch self {
               case .bool(let bool):
                   return "\(bool)"
               case .string(let string):
                   return string
               case .int(let int):
                   return "\(int)"
               case .unsigned(let uInt):
                   return "\(uInt)"
               case .float(let float):
                   return "\(float)"
               case .double(let double):
                   return "\(double)"
               case let .date(date):
                   let dateFormatter = DateFormatter()
                   dateFormatter.dateStyle = .short
                   dateFormatter.timeStyle = .none
                   return dateFormatter.string(from: date)
               case let .dateTime(date):
                   let dateFormatter = DateFormatter()
                   dateFormatter.dateStyle = .short
                   dateFormatter.timeStyle = .short
                   return dateFormatter.string(from: date)
               case .data(let data):
                   return "Data \(data.count) bytes"
               case .map(let dictionary):
                   let result = dictionary.mapValues { value in
                       value.textRepresentation
                   }
                   return "\(result)"
               case .array(let array):
                   return array.reduce("") { partialResult, element in
                       partialResult + element.textRepresentation
                   }
                   .appending("")
               @unknown default:
                   return "Unknown type"
               }
           }
       }

   The DocumentView file comprises the following elements:

   • DocumentView : Basic UI layout for viewing received documents and verification results.
   • DocumentViewModel : This class takes MobileCredentialPresentation and converts its elements into strings to display in the DocumentView.
   • Extension of MobileCredentialElementValue which converts the values of received claims into a human-readable format.

2. Return to the ContentView file and replace the EmptyView() under the // Verify mDocs - Step 4.2: Create PresentationResponseView comment with the following code to display the DocumentView view when verification results are available:

           ZStack {
           if viewModel.receivedDocuments.isEmpty {
               VStack(spacing: 40) {
                   Text("Waiting for response...")
                       .font(.title)
                   ProgressView()
                       .progressViewStyle(.circular)
                       .scaleEffect(2)
               }
           } else {
               ScrollView {
                   ForEach(viewModel.receivedDocuments, id: \.docType) { doc in
                       DocumentView(viewModel: DocumentViewModel(from: doc))
                           .padding(10)
                   }
               }
           }
       }