Android Holder SDK v6.0.0 Migration Guide

A guide to help developers migrate from Android Holder SDK v5.x to v6.0.0, including breaking changes, new features, and best practices.

Overview

This guide provides a comprehensive overview of the changes introduced in MobileCredentialHolderSDK v6.0.0 for Android, including breaking changes, new features, and migration steps.

Key Features

Seamless, OS-native credential presentation (DC API support): The Android Holder SDK now integrates with the Digital Credentials API, allowing credentials to be presented via an OS overlay without launching your holder app. The OS automatically surfaces only matching credentials across installed wallets — reducing friction, avoiding dead ends, and significantly improving the user experience.
Clearer OID4VCI interoperability (v1.0 alignment): The Android Holder SDK now aligns with the finalized OID4VCI v1.0 specification (upgraded from draft-12). This alignment improves interoperability across the ecosystem, enabling other systems to clearly identify your supported version and feature set, ensuring smoother integrations and consistent behavior across platforms.
Improved reliability in contactless flows: Enhanced BLE performance delivers more consistent proximity credential exchanges and faster engagements.
Stronger cryptography and standards alignment: Updated COSE algorithms (as per RFC 9864) strengthen cryptographic compatibility and ensure continued compliance with evolving standards.
Simpler, Decoupled Releases: The Android Holder SDK no longer has a shared common module. This allows us to decouple the releases of Holder and Verifier and versions no longer need to match.
General stability and performance improvements: Multiple refinements reduce integration friction, increase consistency across mobile environments, and improve overall user experience.

For a detailed list of changes included in this release, refer to the SDK Changelog.

Breaking Changes

This section outlines the breaking changes introduced in v6.0.0 that require updates to your existing implementation:

#	Element	Change	Impact
1	`MobileCredentialHolder.getCredential(credentialId,skipStatusCheck = ...)`	Parameter renamed to `fetchUpdatedStatusList = ...` with inverted semantics	All call sites using `skipStatusCheck = ...` must be updated.
2	`OfferedCredential`	New required property `credentialConfigurationId: String`	Manual decoders must handle new field.
3	`VerifierAuthenticationResult`	New subclass `Unsigned(val origin: String?)`	Exhaustive `when` statements must add new case.
4	`MobileCredentialRequest.verifierAuthenticationResult`	No longer nullable	Exhaustive `when` statements, or null checks, must now handle `Unsigned` in place of `null`.
5	`global.mattr.mobilecredential.common`	Renamed `global.mattr.mobilecredential.holder`	All uses of any `common` must be updated to use `holder`.

New Additions

Types

Type	Purpose
`DcmConfiguration`	Configure Digital Credentials support (enable/disable)

Sealed & Enum Classes

Type	New Case
`VerifierAuthenticationResult`	`Unsigned(val origin: String?)`

New Dependencies

androidx.credentials.registry:registry-provider
androidx.credentials.registry:registry-provider-play-services

Bug Fixes

Fixed parsing of status lists that use a bit size other than 2.
Resolved BLE connection stalls on Pixel 7 Pro devices.
Resolved NFC engagement issues on Pixel 6 Pro devices.
Aligned WebView OID4VCI error messages for improved consistency.

Minimum Requirements

Android 7 / Nougat / API 24.
The Android Holder SDK is built using Kotlin 2.0. This adds some intrinsic dependencies into your build tools.
- Kotlin 2.0 is supported from AGP version 8.5.
- AGP 8.5 is supported from Gradle version 8.7 and Android Studio Koala 2024.1.1.

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)

Old Parameter	New Parameter
`skipStatusCheck = false` (default)	`fetchUpdatedStatusList = true` (default)
`skipStatusCheck = true`	`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 are using the default decoding provided by the SDK, no changes are needed. However, if you have implemented a custom decoder for OfferedCredential, you must update it 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"
  }

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>