Android Holder SDK v6.0.0 Migration Guide

Rename any references to the common dependency to holder

The shared common module has been removed and the Android Holder SDK is now published as holder. This means that any references to global.mattr.mobilecredential.common in your codebase should be updated to global.mattr.mobilecredential.holder.

This can be done with a global find and replace across your codebase. If you are using both the Holder and Verifier SDKs, you will need to limit your search to the relevant parts of your application.

Update getCredential calls

The skipStatusCheck parameter has been renamed to fetchUpdatedStatusList with inverted semantics. When fetchUpdatedStatusList is true (default), the SDK will fetch the latest status list to ensure up-to-date revocation information. When false, it will skip fetching the status list and rely on cached data (when valid). Update all calls accordingly:

- val credential = holder.getCredential(credentialId = id, skipStatusCheck = true)
+ val credential = holder.getCredential(credentialId = id, fetchUpdatedStatusList = false)

Refer to Revocation Status check for more information.

Handle OfferedCredential changes

The OfferedCredential data class now includes a new required property val credentialConfigurationId: String. If you have custom encoding or decoding logic for this object, make sure it is updated to handle the new field:

  data class OfferedCredential(
      val doctype: String,
      val claims: List<Claim>,
      val name: String?,
+     val credentialConfigurationId: String,
      internal val scope: String
  )

Handle VerifierAuthenticationResult changes

The VerifierAuthenticationResult sealed class now includes a new subclass Unsigned(val origin: String?) to represent unsigned/unauthenticated requests. If you have any exhaustive when statements on VerifierAuthenticationResult, you must add a new case to handle this scenario:

  val trusted = when (verifierAuthenticationResult) {
      is Trusted ->
          "Trusted verifier"
      is Untrusted ->
          "Authentication failed")
-     else ->
+     is Unsigned ->
          "No authentication"
  }

Handle NFC device engagement changes

Starting with Android Holder SDK v6.0.0, the SDK automatically launches an Activity when NFC device engagement occurs. Manual Activity launching from your NFC engagement listener is no longer required.

To migrate your implementation, make the following changes:

1. In your AndroidManifest.xml, add the following intent-filter to the Activity that should be started (or brought to the foreground) when NFC device engagement begins:

<intent-filter>
    <action android:name="global.mattr.mobilecredential.holder.NFC_RECEIVER_ACTIVITY" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

Any Activity that declares this intent filter will be automatically launched by the SDK when NFC device engagement starts.

2. Remove any manual Activity launching logic from your NFC engagement listener.

3. Your NFC device engagement listener should now only handle UI updates (for example, displaying your NFC screen). It should no longer start an Activity. It is recommended to register the listener in the NFC Activity’s onCreate() method (or in a related ViewModel), rather than in your Application class:

   -class YourApplication : Application() {
   +class NfcActivity : Activity() {
   
       override fun onCreate() {
           super.onCreate()
           MobileCredentialHolder.Nfc.setDeviceEngagementListener {
   -           startNfcActivity()
   +           showNfcUI()
           }
       }
   }

4. To improve the user experience on devices with multiple NFC-capable mobile credential wallets, you can optionally explicitly mark your Activity as the preferred NFC handler while it is in the foreground:

   override fun onResume() {
       super.onResume()
       MobileCredentialHolder.Nfc.onActivityResume(this)
   }
   
   override fun onPause() {
       MobileCredentialHolder.Nfc.onActivityPause(this)
       super.onPause()
   }

   This ensures your Activity is prioritised for NFC handling while visible.

Enable Presenting Credentials via the Digital Credentials API (Optional)

The Android Holder SDK v6.0.0 introduces support for the Digital Credentials API, allowing credentials to be presented via an OS-native overlay without launching your app. To enable this feature, you need to initialize the SDK with a DcmConfiguration that sets enabled to true. This is optional but recommended for a seamless user experience.

  MobileCredentialHolder.getInstance().initialise(
      // ...
+     dcmConfiguration = DcmConfiguration(enabled = true)
  )

Enable Confirmation and Error Handling for the Digital Credentials API (Optional)

The Digital Credentials API support includes new intents for handling confirmation and error scenarios during credential presentation. To enable this, you need to add intent filters to your AndroidManifest.xml and handle the incoming intents in your activity:

<intent-filter>
    <action android:name="global.mattr.credentialmanager.action.CONFIRMATION" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

val verifierAuthenticationResult =
    IntentCompat.getParcelableExtra(
        intent,
        "global.mattr.credentialmanager.extra.verifier_authentication_result",
        VerifierAuthenticationResult::class.java
    )

<intent-filter>
    <action android:name="global.mattr.credentialmanager.action.ERROR" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>