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

Coming soon...

Coming soon...

• Complete the sign up form to get trial access to MATTR VII and the MATTR Portal, and then Create a tenant.
• As part of your MATTR Pi SDK onboarding process you should have been provided with access to the following SDK resources:
  • ZIP file which includes the required framework: (MobileCredentialVerifierSDK-*version*.xcframework.zip).
  • Sample Verifier app: You can use this app for reference as you work through this tutorial.

Coming soon...

Coming soon...

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

Coming soon...

Coming soon...

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

• Available internet connection
• A wallet application that can present an mDoc remotely. If you don't have one available, we recommend using the app built in our Holder SDK remote presentation tutorial.
• Use your testing wallet application to claim an mDoc by scanning the following QR code:

Coming soon...

Coming soon...

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-*version*.xcframework.zip file.
2. Drag the MobileCredentialVerifierSDK-*version*.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:

Coming soon...

Coming soon...

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
   internal import Combine
   // Step 2.3: Import MobileCredentialVerifierSDK
   
   struct ContentView: View {
       @ObservedObject 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
   
   final class VerifierViewModel: ObservableObject {
       @Published 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
       )

   This instance configures the MATTR VII tenant that the SDK will interact with (tenantHost) based on the constants defined in the Constants file.

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() {
           do {
               mobileCredentialVerifier = MobileCredentialVerifier.shared
               try mobileCredentialVerifier.initialize(platformConfiguration: platformConfiguration)
           } catch {
               print(error.localizedDescription)
           }
       }

7. Run the app to ensure it compiles successfully.

Coming soon...

Coming soon...

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).

   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:

       @Published 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], challenge: UUID().uuidString, applicationId: Constants.applicationID)
                   guard let receivedCredentials = onlinePresentationResult.mobileCredentialResponse?.credentials else {
                       let errorMessage = onlinePresentationResult.error?.message ?? "No error message"
                       print("No response received: \(errorMessage)")
                       return
                   }
                   receivedDocuments = receivedCredentials
               } catch {
                   print(error.localizedDescription)
               }
           }

   The following parameters are passed to the requestMobileCredentials method:

   • request : Defines what information to request. This example is passing the mobileCredentialRequest instance you created in the previous step.
   • challenge : Unique challenge generated by the SDK to identify this specific presentation session. Should be a unique, unpredictable value generated for each verification session to mitigate replay attacks by ensuring the response from the wallet app is tied to the current request and cannot be reused maliciously. Always generate a new challenge for every same credential request.
   • applicationId : Identifier of the application that will be used to verify the request. In this example it is retrieved from the information defined in the Constants file.

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.

Coming soon...

Coming soon...

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 io.mattrlabs.dev.sampleApp.MdocSampleApp 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
   
       class DocumentViewModel: ObservableObject {
           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.reason?.message
   
               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)
                   }
               }
           }
       }

Coming soon...

Coming soon...

Coming soon...

Coming soon...