Present mDL in-person/offline

Present an ISO/IEC 18013-5 mDL over BlueTooth Low Energy

This guide is for iOS applications. Building for Android? Look here: Present an mDL in-person/offline

To present an mDL over BLE, you will need to use the following components:

• The CredentialStore Component

• The IsoMdlPresentation Component

To use these components in your mobile application, we encourage you to define:

• A Delegate class that holds the BLESessionState and the ISO mDL SessionManager

  • This class should implement the BLESessionState protocol.

• A View that manages the UI based on the BLESessionState

  • The View holds an instance of your delegate class.

During the presentation, you will have to manage the BLESessionState. The BLESessionState definition is repeated here to show the stages that the presentation goes through. The View that manages your UI should deal with each one of these listed cases. Again, we have an example to give you some inspiration.

// The different Wallet-side states of an mDL presentation.

public enum BLESessionState {
    /// App should display the error message
    case error(BleSessionError)
    /// App should display the QR code
    case engagingQRCode(Data)
    /// App should indicate to the user that BLE connection has been made
    case connected
    /// App should display an interactive page for the user to chose which values to reveal
    case selectNamespaces([ItemsRequest])
    /// App should display the fact that a certain percentage of data has been sent
    /// - Parameters:
    ///   - 0: The number of chunks sent to far
    ///   - 1: The total number of chunks to be sent
    case uploadProgress(Int, Int)
    /// App should display a success message and offer to close the page
    case success
}

1. Start a Session by generating a QR-Code

import SpruceIDMobileSdk
import SpruceIDMobileSdkRs

let credentialPack = CredentialPack()
// Retrieve mdoc(s) from the credentialPack by their ID.
let credentials = credentialPack.get(credentialIds: [mdocId])
// The CredentialStore is a wrapper for in-person mdoc presentment.
// Initiate your CredentialStore with an array of ParsedCredentials
let credentialStore = CredentialStore(credentials: credentials)

/*
Start an ISO/IEC 18013-5 SessionManager from your credential store.
Here, the deviceEngagement is an enum, currently only supporting QRCode engagement
The callback should be an instance of the class that implementes the BLESessionStateDelagate Protocol.
*/
let sessionManager = await credentialStore.presentMdocBLE(deviceEngagement: .QRCode, callback: <yourSessionDelegate> )!

/*
submit user selected datafields through the sessionManager. 
*/
let _ = sessionManager.submitNameSpaces(items: )

In the delegate class, make sure you can call the presentMdocBLE and submitNamespaces methods on the IsoMdlPresentation component.

2. Define your Session Delegate

// Your Delegate Class
import SpruceIDMobileSdk
import SpruceIDMobileSdkRs

class MDLDelegate: ObservableObject {
    @Published var state: BLESessionState = .connected
    private var sessionManager: IsoMdlPresentation?
    
    init(credentials: CredentialStore) async {
        self.sessionManager = await credentials.presentMdocBLE(deviceEngagement: .QRCode, callback: self)!
    }
    
    func cancel() {
        self.sessionManager?.cancel()
    }
    
    func submitItems(items: [String: [String: [String: Bool]]], key: SecKey) {
        self.sessionManager?.submitNamespaces(items: items.mapValues { namespaces in
            return namespaces.mapValues { items in
                Array(items.filter { $0.value }.keys)
            }
        }, signingKey: key)
    }
}

Now that you have your Delegate to manage the BLESessionSate and your SessionManager, you can define the View that defines what your presentation flow looks like.

3. Define your Mdl Sharing View

// Your mDL Sharing View

public struct MDLSharing: View {
    var credentials: CredentialStore
    @State var proceed = true
    @StateObject var delegate: MDLDelegate
    
    init(credentials: [ParsedCredential]) async {
        let credentialStore = CredentialStore(credentials: credentials)
        self.credentials = credentialStore
        let viewDelegate = await ShareViewDelegate(credentials: credentialStore)
        self._delegate = StateObject(wrappedValue: viewDelegate)
    }
    
    public var body: some View {
        VStack {
            if proceed {
                switch self.delegate.state {
                // Manage the UI for your BleSessionStates here
            } else {
                Text("Operation Canceled")
            }
        }
    }
}

You will need a UI component that allows the user to select which fields of the mDL they are willing to share. In our SpruceKit Showcase App, we call that the Credential Selector

That's it! You manage the UI, and SpruceKit takes care of all the nitty gritty underneath.