How to build mDocs claiming capabilities into my iOS application

This guide offers step-by-step instructions for using the iOS mDocs holder SDK to build the capability to claim an mDoc into an iOS wallet application via an OID4VCI workflow.

If you are unfamiliar with this workflow, the corresponding tutorial might be a better starting point as it offers more context and a high level overview of the user experience.

Prerequisites

The clientId used to identify your wallet application by the issuer you are going to claim credentials from.
Access to the SDK’s GitHub distribution repository. Refer to the getting started guide for more information.

Access requires an SSH key associated with the GitHub user who has access to the distribution repo. Please contact us if you are having trouble with setting this up.

Overview

This guide comprises the following steps:

Setup your project.
Initialise the SDK.
Discover a credential offer.
Present offer to user.
Initiate issuance workflow.

Setup your project

Install the SDK.
Create a new file named Constants.swift and define the following resources:
- redirectUri: The path the SDK will redirect to once the user completes Authentication with the issuer.
- clientId: The identifier used by the issuer to recognise your wallet application.

Resource definition

enum Constants {
	static let redirectUri: String = "io.mattrlabs.sample.mobilecredentialholderapp://credentials/callback"
	static let clientId: String = "ios-sample-mobile-credential-holder-app"
}

Add Bluetooth and Biometric permissions to your application.

Initialise the SDK

Create a new variable:

Creating a new variable

	var mobileCredentialHolder: MobileCredentialHolder

Initialise the SDK by creating a new instance of the MobileCredentialHolder class and calling its initialise function:

Initialising the SDK

    mobileCredentialHolder = MobileCredentialHolder.shared
	try mobileCredentialHolder.initialise()

Discover a credential offer

Call the discoverCredentialOffer function with a String parameter to discover the credential offer:

Discovering the Credential offer

func discoverCredentialOffer(_ offer: String) {
    Task { @MainActor in
        do {
            discoveredCredentialOffer = nil
            discoveredCredentialOffer = try await mobileCredentialHolder.discoverCredentialOffer(offer)
        } catch {
        }
    }
}

The String parameter is a URL-encoded Credential offer which your application must extract from a received Credential offer. Based on your implementation, this offer might be formatted as a QR code, deep-link or app notification. Refer to the tutorial for an example of extracting the URL from a QR code.

The function will return a DiscoveredCredentialOffer object, which we will use in the next step.

Display offer to user

Extract the issuer and credentials elements from the DiscoveredCredentialOffer object and present this information to the user for review, alongside any other information you might think is relevant.

Initiate the issuance workflow

Create a UI element that enables the user to consent to claiming the credentials included in the Credential offer.
Once the user provides consent, your application must call the retrieveCredentials function to trigger the credential issuance.

Retrieving the offered credentials

func retrieveCredential() {
    Task { @MainActor in
        do {
            retrievedCredentialResults = try await mobileCredentialHolder.retrieveCredentials(
                credentialOffer: discoveredCredentialOffer!,
                clientId: Constants.clientId,
                redirectUri: Constants.redirectUri,
                autoTrustMobileCredentialIaca: true)
        } catch {
            print(error.localizedDescription)
        }
    }
}

credentialOffer: This is the DiscoveredCredentialOffer object returned by the discoverCredentialOffer function.
clientId: This was configured when setting up your project. It is used by the issuer to identify the wallet application that is making a request to claim credentials.
redirectUri: This was configured when setting up your project. It is used by the SDK to redirect the user back to a specific wallet application view after completing authentication.

The function returns a RetrieveCredentialResult array.

Call the getCredential function with a credentialId parameter (extracted from the RetrieveCredentialResult array).

The function returns a MobileCredentialResponse object.

Create a new variable to hold the MobileCredentialResponse object and add a UI element to display it to the user.

@Published var credential: MobileCredential?
 
...
 
credential = try await mobileCredentialHolder.getCredential(credentialId: retrievedCredentialResults![0].credentialId!)

Install the SDK Proximity presentation