Learn how to build an application that can verify an mDoc from another app on the same device

• 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 MATTR Pi SDK onboarding process you will be provided with access to the following resources:
  • ZIP file which includes the required framework: (MobileCredentialVerifierSDK.xcframework.zip).
  • Sample Verifier app: You can use this app for reference as you 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.

Supported iOS device to run the built Verifier application on, setup with:

• Available internet connection
• A wallet application that can present an mDoc remotely as per ISO/IEC 18013-7 and OID4VP. We recommend using the sample holder app you can build with our Holder SDK quickstart guide.
• Use your testing wallet application to claim an mDoc by scanning the following QR code:

Step 1: Create a new project

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: 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:

The first capability you will build into your app is to initialize the SDK so that the app can use its functions and classes. To achieve this, you need to import the MobilecredentialVerifierSDK framework and then initialize the MobileCredentialVerifier class.

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

   import SwiftUI
   // Step 2.3: Import MobileCredentialVerifierSDK
   
   struct ContentView: View {
       @State var viewModel: VerifierViewModel = VerifierViewModel()
   
       var body: some View {
           NavigationStack(path: $viewModel.navigationPath) {
               VStack {
                   Button("Request credentials") {
                       viewModel.requestCredentials()
                   }
                   .padding()
               }
               .navigationDestination(for: NavigationState.self) { destination in
                   switch destination {
                   case .viewResponse:
                       presentationResponseView
                   }
               }
           }
           // Step 4.2: Handle MATTR VII redirect
   
       }
   
       // MARK: Verification Views
   
       var presentationResponseView: some View {
           // Step 4.4: Create PresentationResponseView
           EmptyView()
       }
   }
   
   // MARK: VerifierViewModel
   
   @Observable
   final class VerifierViewModel {
       var navigationPath = NavigationPath()
       // Step 2.4: Setup platform configuration
   
       // Step 2.5: Add MobileCredentialVerifier var
   
       // Step 2.6: Initialize the SDK
   
       // Step 3.1: Create MobileCredentialRequest instance
   
       // Step 3.2: Create receivedDocuments variable
   
   }
   
   // MARK: Same Device Verification
   
   extension VerifierViewModel {
       func requestCredentials() {
       // Step 3.3: Request credentials
       }
   }
   
   // MARK: - Navigation
   enum NavigationState: Hashable {
       case viewResponse
   }

   This will serve as the basic structure for your application. You will copy and paste different code snippets into specific locations to achieve the different functionalities. These locations are indicated by comments that reference both the section and the step.

   We recommend copying and pasting the comment text in Xcode search field (e.g. Step 2.3: Import MobileCredentialVerifierSDK) to easily locate it in the code.

2. Create a new file named Constants and paste the following code into it to define constants which are required to initialize the SDK:

   import Foundation
   
   enum Constants {
       static let tenantHost = URL(string: "https://learn.vii.au01.mattr.global")!
       static let applicationID = "74f91a0f-5909-43b0-a431-6da2397d1f86"
   }

   • tenantHost : Replace with the URL of your MATTR VII tenant.
   • applicationID : Replace with the id returned when you created the MATTR VII verifier application.

3. Return to the ContentView file and add the following code after the Step 2.3: Import MobileCredentialVerifierSDK comment to import MobileCredentialVerifierSDK and gain access to the SDK capabilities:

   import MobileCredentialVerifierSDK

4. Add the following code under the Step 2.4: Setup platform configuration comment to create a PlatformConfiguration instance:

       let platformConfiguration = PlatformConfiguration(
           tenantHost: Constants.tenantHost,
           applicationId: Constants.applicationID
       )

   This instance configures the MATTR VII tenant that the SDK will interact with (tenantHost) and the Verifier Application the SDK represents (applicationId), based on the constants defined in the Constants file. From v6.0.0, the applicationId is supplied here via PlatformConfiguration (it is no longer passed to requestMobileCredentials), and it also drives the SDK Backend.

5. Add the following code after the Step 2.5: Add MobileCredentialVerifier var comment to create a variable that will hold the mobileCredentialVerifier instance when the SDK is initialized:

       var mobileCredentialVerifier: MobileCredentialVerifier

6. Add the following code after the Step 2.6: Initialize the SDK comment to initialize the MobileCredentialVerifier instance with the parameters defined in the platformConfiguration instance:

       init() {
           mobileCredentialVerifier = MobileCredentialVerifier.shared
           Task {
               do {
                   try await mobileCredentialVerifier.initialize(platformConfiguration: platformConfiguration)
               } catch MobileCredentialVerifierError.failedToRegister {
                   // Registration with the MATTR VII tenant failed during SDK Backend setup.
                   // Print the reason so the failure is visible: check connectivity and that
                   // tenantHost, applicationId, and the app's bundle identifier / team ID match
                   // the Verifier Application configuration.
                   print("SDK initialization failed to register:", MobileCredentialVerifierError.failedToRegister)
               } catch MobileCredentialVerifierError.invalidLicense {
                   // The SDK license is missing, invalid, or expired.
                   print("SDK initialization failed: invalid license")
               } catch {
                   print("SDK initialization failed:", error.localizedDescription)
               }
           }
       }

   The initialize method is asynchronous (called here from a Task) and drives the SDK Backend: on first launch it registers the app instance with your tenant and obtains a license. Network access is required the first time the SDK initializes and when the license is later renewed.

7. Run the app to ensure it compiles successfully.

1. Open the ContentView file and add the following code under the Step 3.1: Create MobileCredentialRequest instance comment to create a new MobileCredentialRequest instance:

       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 defines what information is required for verification:

   • 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). Declarative only and not currently enforced by the SDK. 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 Step 3.2: Create receivedDocuments variable comment to create a new receivedDocuments variable that will hold the response received from the wallet application:

       var receivedDocuments: [MobileCredentialPresentation] = []

3. Add the following code under the Step 3.3: Request credentials comment to call the SDK's requestMobileCredentials method:

           Task { @MainActor in
               // Clean the response before fetching a new one
               receivedDocuments = []
               do {
                   let onlinePresentationResult = try await mobileCredentialVerifier.requestMobileCredentials(request: [mobileCredentialRequest])
                   // From v6.0.0, OnlinePresentationSessionResult is a @frozen enum with
                   // success and failure cases.
                   switch onlinePresentationResult {
                   case .success(_, _, let mobileCredentialResponse):
                       receivedDocuments = mobileCredentialResponse?.credentials ?? []
                   case .failure(_, _, let error):
                       print("No response received: \(error.message)")
                       return
                   }
               } catch {
                   print(error.localizedDescription)
               }
           }

   The following parameter is passed to the requestMobileCredentials method:

   • request : Defines what information to request. This example is passing the mobileCredentialRequest instance you created in the previous step.

   From v6.0.0, the applicationId is no longer passed here — it is supplied via PlatformConfiguration when you initialize the SDK. The challenge parameter is now optional: when omitted, the SDK generates a cryptographically secure challenge for you. You can still pass your own challenge (a unique, unpredictable value per session) to mitigate replay attacks if you prefer to manage it yourself.

4. Run the app and press Request credentials button.

   You will be redirected to a compliant wallet application, where you will see the verification request details and choose what mDoc to present for verification.

Once you send the response from the wallet nothing will happen, which is expected at this stage. In the next step you will build the capability to redirect the user back to the verifier application and handle the response from the wallet.

To enable the redirect back to your verifier application you must register a redirection link. This could be either a Universal link or a custom URL scheme. In this tutorial you will use a custom URL scheme.

1. Register a custom URL scheme in your verifier application:

   • Open the project view and select your application target.
   • Select the Info tab.
   • Scroll down and expand the URL Types area.
   • Select the plus button.
   • Insert your app bundle identifier (as set when you configured the MATTR VII verifier application) in both the Identifier and URL Schemes fields.

2. In your ContentView file, add the following code under the Step 4.2: Handle MATTR VII redirect comment to handle the redirect from the wallet application:

           .onOpenURL { url in
               // Navigate to response screen
               viewModel.navigationPath.append(NavigationState.viewResponse)
               viewModel.mobileCredentialVerifier.handleDeepLink(url)
           }

   This will pass the redirect URL to the SDK's handleDeepLink method, which will process the response from the wallet application and update the receivedDocuments variable with the verification results.

3. Create a new file named DocumentView and add the following code to display the retrieved 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 that are displayed in the DocumentView.
   • Extension of MobileCredentialElementValue which converts the values of received claims into a human-readable format.

4. Return to the ContentView file and replace the EmptyView() under the Step 4.4: 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)
                   }
               }
           }
       }