NFC device engagement for proximity presentations

Overview

This guide shows how to configure the Holder SDK to start a proximity presentation session using device engagement over NFC.

NFC-based device engagement is a convenient alternative to QR-code engagement: it is faster, simpler for users, and fully handled by the SDK.

It also simplifies your application because you do not need to generate a QR code or process engagement data manually.

Prerequisites

This guide builds on knowledge obtained in the Proximity Presentation tutorial. It is recommended to complete that tutorial first, then return here to learn how to configure NFC device engagement.

Understanding NFC Device Engagement

Device engagement is the initial stage of a proximity presentation session defined in ISO/IEC 18013-5:2021. During engagement, the Holder sends the information required to establish a secure connection to the Verifier. This information contains cipher suite, ephemeral device key, and channel parameters, as well as its preferred BLE role and the associated connection details.

In the Proximity Presentation tutorial this data was encoded into a QR code that the Verifier scanned to establish the channel and encryption. With NFC the Verifier reads the engagement data directly from the Holder device, with no QR code generation, scanning or handling required.

NFC-based engagement supports two modes (as per ISO/IEC 18013-5:2021):

• Static Handover: The Holder sends its connection details to the Verifier.
• Negotiated Handover: The Verifier sends its supported data transfer options, then the Holder selects one and returns its connection details.

A key advantage of NFC-based engagement is that the user can start it without first opening the app. Similar to NFC payments, the user brings the device near the Verifier's device and the Holder app launches automatically. If multiple NFC-capable Holder apps are installed, the system prompts the user to choose one. A default app can be set in the device's system settings.

Configuring NFC-based Engagement

Configuration involves the following steps:

1. Register the NFC-based engagement listener: set up a listener to receive NFC engagement events.
2. Handle device engagement and create a proximity presentation session: respond to engagement events by creating a presentation session.

Step 1: Register the NFC-based engagement listener

After you include the SDK, your Holder app becomes NFC-capable and will be launched (or suggested) when near an NFC-enabled verifier. The SDK automatically performs the engagement, but you must register a listener to receive events. Do this as early as possible in the app lifecycle.

override fun onCreate() {
    super.onCreate()
    MobileCredentialHolder.Nfc.setDeviceEngagementListener { error ->
        if (error == null) {
            // Create the session and show consent UI (e.g. start an Activity)
        } else {
            Log.e("HolderApplication", "NFC engagement error: ${error.message}")
        }
    }
}

Step 2: Handle device engagement

Start a proximity presentation session (the same way as you do for QR-based device engagement) while setting engagementFromNfc = true to indicate NFC was used:

val mdocHolder = MobileCredentialHolder.getInstance()

// Minimal initialization logic
// However, if you support multiple instances, you probably want to add more robust initialization logic
if (!mdocHolder.initialized) mdocHolder.initialize(activity)

mdocHolder.createProximityPresentationSession(
    activity,
    onRequestReceived = { _, requests, e ->
        // Show consent UI for requests or handle error
    },
    engagementFromNfc = true
)

• Your consent UI might appear when the app is already running or as the first screen after launch.
• Ensure the SDK is initialized before creating a presentation session.

Optional steps

Configure branding

Help users recognize your app in system prompts and settings by overriding NFC engagement resources:

<string name="mattr_nfc_engagement_description">Your application name.</string>

Set preferred BLE role and log level

Set optional NFC configuration options that apply to subsequent NFC engagements, regardless of SDK initialization.

Calling this API does not require the SDK to be initialized.

MobileCredentialHolder.Nfc.setNfcConfiguration(
    context,
    NfcConfiguration(
        handoverMode = NfcHandoverMode.Negotiated,
        bleMode = BleMode.MDocClientCentral,  // Used only for Static Handover to set preferred BLE role
        logLevel = LogLevel.ERROR             // Log level if SDK not initialized yet
    )
)

Testing NFC-based Engagement

To test NFC-based engagement:

1. Claim a credential in a holder app.
2. Use an NFC-capable verifier device and request to verify the credential claimed in the previous step.
3. Bring the devices close to each other to establish NFC connection.
4. Confirm the Holder app launches (or is suggested if multiple NFC-capable apps exist).
   If multiple NFC-capable apps exist, select yours.
5. Approve the verification request.
6. Confirm the credential is presented successfully to the verifier.