Holder SDK quickstart guide

1. Access the sample holder codebase by either:

   • Cloning the MATTR Sample Apps repository:

     git clone https://github.com/mattrglobal/sample-apps.git

   • Or downloading just the iOS sample holder project using download-directory.github.io.

2. Use Xcode to open the .xcodeproj file in the project's folder. You can find it in the sample-apps/ios-holder-tutorial-sample-app directory.

3. Drag the MobileCredentialHolderSDK-*version*.xcframework folder (obtained from MATTR as part of the SDK package) into your project.

4. Configure MobileCredentialHolderSDK-*version*.xcframework to Embed & sign.

5. Set a unique bundle identifier for the project in the Xcode project settings (e.g., com.yourname.holdersample).

6. Run the project on a physical iOS device (simulators do not support the required Bluetooth capabilities).

1. Use a mobile browser on the device where the sample application is installed to navigate to the MATTR Labs remote presentation testing tool.
2. Select the OID4VP (Redirect) option from the Select Experience list.
3. Select Request credentials.
4. Select Allow to open the sample application.
5. Select the credential you claimed in the previous part.
6. Select Send Response.
7. You should be redirected back to the MATTR Labs remote presentation testing tool, where you will see a successful verification indication.

try await mobileCredentialHolder.initialize(
    userAuthenticationConfiguration: UserAuthenticationConfiguration( 
        userAuthenticationBehavior: .always, 
        userAuthenticationType: .biometricOrPasscode, 
        presentationTimeoutSeconds: 20
    ),
    credentialIssuanceConfiguration: CredentialIssuanceConfiguration(
        redirectUri: "<WalletRedirectUri>", 
        autoTrustMobileCredentialIaca: true
    ),
    dcConfiguration: DCConfiguration( // iOS 26+ only
        appGroup: "group.com.yourcompany.app", 
        supportedDocTypes: [.mDL, .eudi] 
    ) 
)

• userAuthenticationConfiguration: Optional. Configures when the SDK requires user authentication to access or present credentials. The example shows the default values. Refer to the reference documentation for additional details about the available configuration options.
• redirectUri : Provide a URL that corresponds to a specific path in your application. The SDK will redirect the user to this path after they successfully complete authentication. Required for the Authorization Code flow.
• autoTrustMobileCredentialIaca : Set to true if you trust the credential issuer(s) for any offer. Defaults to false.
• dcConfiguration: Optional, iOS 26+ only. Configures Digital Credentials API support for presenting credentials via an OS-native overlay. Specify your app group and supported document types (e.g., .mDL, .eudi, .euav, .photoid, .jpMnc).

    let discoveredOffer = try await mobileCredentialHolder.discoverCredentialOffer(offerUrl: String)

• offerUrl : Pass the OID4VCI initiation URL.

The discoverCredentialOffer method returns a DiscoveredCredentialOffer object containing the offer details.

let retrievedCredentialResults = try await mobileCredentialHolder.retrieveCredentials(
    credentialOffer: String, 
    clientId: "<WalletClientID>", 
    transactionCode: nil
)

• credentialOffer : Pass the OID4VCI credential offer URI.
• clientId : Pass a string that identifies your wallet application with the issuer.
• transactionCode : Provide a transaction code if the Pre-Authorization Code flow offer requires a transaction code.

The retrieveCredentials method returns an array of RetrieveCredentialResult objects, each containing the metadata of the retrieved credentials, including the credential ID (credentialId).

let credential = try mobileCredentialHolder.getCredential(credentialId: String)

• credentialId : Pass the credential ID of the credential you want to access.

Ensure that your application is registered to handle the verifier's authorization URL. This is typically done in the app's Info.plist file. The URL scheme should match the one used by the verifier.

    let onlinePresentationSession = try await mobileCredentialHolder.createOnlinePresentationSession(authorizationRequestUri: authorizationRequestURI, requireTrustedVerifier: false)

• authorizationRequestURI : Pass the OID4VP authorization request URI as a string.
• requireTrustedVerifier : Set to true if you want to ensure that the verifier exists on the app's trusted verifier's list.

The createOnlinePresentationSession method returns an instance of OnlinePresentationSession containing requested and matching credentials.

    let credential = try await mobileCredentialHolder.getCredential(credentialId: id)

• id : Pass the identifier of the credential you want to present, as a string. This information can be retrieved from the OnlinePresentationSession object returned by the createOnlinePresentationSession method.

Your application must then gather the user's consent to share the matching credential with the verifier.

    try await onlinePresentationSession.sendResponse(credentialIds: [id])

• id : Pass the identifier of the credential you want to send, as a string.

    let proximityPresentationSession = try await mobileCredentialHolder.createProximityPresentationSession(
                    onRequestReceived: onRequestReceived(_:error:)
                    // 1. Callback triggered when the verifier requests a credential for verification. Use this callback to display the request on the UI and get the user's consent to share any matched credentials.
                )

The createProximityPresentationSession method returns an instance of ProximityPresentationSession which contains a deviceEngagement property that must be shared with the verifier embedded in a QR code to establish a secure connection.

    let credential = try await mobileCredentialHolder.getCredential(credentialId: id)

• id : Pass the identifier of the credential you want to present, as a string. This information is returned by the createProximityPresentationSession method on a onRequestReceived event, triggered when the verifier requests a credential for verification.

Your application must then gather the user's consent to share the matching credential with the verifier.

    try await proximityPresentationSession.sendResponse(credentialIds: [id])

• id : Pass the identifier of the credential you want to send, as a string.