Android Holder SDK v8.0.0 Migration Guide
A guide to migrating to Android Holder SDK v8.0.0, covering breaking changes, new features, and step-by-step migration instructions.
This is a draft migration guide, shared ahead of general availability to help you gauge migration effort and plan ahead of the release. We will update this page to a final copy when the SDK is generally available.
Overview
This guide describes the changes introduced in the Android Holder SDK v8.0.0, including breaking changes, new features, and migration steps.
Key Features
- Credential update via refresh token: A wallet can check whether the issuer has a newer version of a credential it already holds, and obtain it without the user claiming the credential again. The SDK replaces the stored credential in place. Refer to credential update for more information.
- SDK Backend (required): Every app instance registers with your MATTR VII tenant on first initialization, and the SDK obtains and renews its license automatically. This lets you see every registered app instance from your tenant, and is required for features that depend on it, such as wallet attestation.
- Standalone logger configuration: Logging is configured with the new
configureLoggermethod, independently of initialization. You can turn logging on beforeinitializeto capture logs from initialization itself, and change log settings without initializing the SDK again. - Claim set support in issuance results:
RetrieveCredentialResultnow reports the credential reference, bundle, and identifier each result relates to, so you can match issued credentials to claim sets. - Verifier identity metadata and authorization (Preview): The SDK reads relying party identity metadata (such as display name and logo) and authorization data from authenticated verifier certificates in online, proximity, and Digital Credentials API presentations.
- More precise errors: Credential offer errors and device authentication errors are now thrown as specific exceptions, so your app can respond to each condition directly.
- Smaller public API: Types that are only used by the Verifier SDK, and internal types, are no longer part of the Holder SDK.
Breaking Changes
This section outlines the breaking changes introduced in v8.0.0 that require updates to your existing implementation:
| # | Change | Impact |
|---|---|---|
| 1 | The SDK Backend is required: platformConfiguration is now a required parameter of initialize, with no default | Create a holder application on your MATTR VII tenant and pass platformConfiguration to initialize as a named argument. |
| 2 | The loggerConfiguration parameter is removed from initialize | Call MobileCredentialHolder.configureLogger instead. |
| 3 | LoggerConfiguration and LogLevel are now top-level types, logDir is removed, the LogLevel constants are renamed, and the log callback receives a LogEvent | Update imports, LogLevel references, and your log callback. |
| 4 | logLevel is removed from NfcConfiguration | Remove the argument. NFC logging is controlled by configureLogger. |
| 5 | The SDK no longer includes Timber as a dependency | No change is required unless your app uses Timber for its own logging. In that case, add Timber as a dependency of your app. |
| 6 | RetrieveCredentialResult.Success and Failure have new properties | Update code that constructs or destructures these classes. |
| 7 | MobileCredentialVerificationResult and TrustedCertificateVerificationResult are serialized with the key failureType instead of reason | Update any code that persists or parses these serialized forms. |
| 8 | VerifiedBy.Certificate exposes verifierInfo instead of commonName | Read verifierInfo.commonName. |
| 9 | Verifier-only types and internal types are removed from the Holder SDK | Remove any references to them. |
| 10 | Credential offer errors are reported more consistently | Catch InvalidCredentialOfferException for offers your wallet cannot accept. |
| 11 | Device authentication exceptions are thrown directly instead of being wrapped | Catch the specific exceptions instead of inspecting cause. |
| 12 | Online presentation requests are validated more strictly | Requests whose client_id is not a valid DNS hostname now fail with InvalidAuthorizationRequestUriException. |
| 13 | CredentialEventType has a new CredentialUpdated value | Handle the new value in exhaustive when statements. |
Migration Steps
Create a holder application on your MATTR VII tenant
The SDK Backend is now required, so the SDK must connect to a holder application configured on your MATTR VII tenant. To create one in the MATTR Portal:
- Log in to the MATTR Portal and expand the Credential holding section in the left-hand navigation panel.
- Select Applications, then select the Create new button.
- Use the Name text box to insert a meaningful and friendly name for your application.
- Use the Client ID text box to insert the OAuth 2.0
client_idvalue that your holder application uses when requesting client attestations. This value must match theclient_idconfigured by issuers who trust this Holder Application. For more detail, see agreeing on a client identifier. - Use the Type radio button to select Android.
- Use the Package name text box to insert the package name of your Android application.
- Use the Signing certificate thumbprints field to insert the SHA-256 hex-encoded fingerprints of the signing key certificates used to sign your APK or app bundle. This ensures the tenant only accepts requests from known and trusted applications. Refer to Android app signing for more information.
- Use the Key Attestation toggle to set whether Key Attestation is Active or Inactive. When active, the app instance must provide a valid Key Attestation during registration and token renewal. When inactive, the app can register and renew tokens using an authentication assertion only. Refer to attestation vs assertion fall back for more information.
- Use the Max time offline field to set the maximum time the SDK can operate offline before requiring a new license token from the configured MATTR VII backend. The minimum is 1 day and the maximum is 30 days. The default is 7 days. Refer to token validity and offline use for more information.
- Select the Create button to create the application and display its detail screen.
- Copy and record the
IDvalue. You use it when initializing the SDK so that it can correctly identify and authenticate your application.
Prefer the API? You can create the holder application with a POST /v1/holder/applications request
instead. Refer to configure holder applications
for the full API request and field reference.
Pass platformConfiguration to initialize
platformConfiguration is now a required parameter of initialize. It is also now the third
parameter, after context and instanceId, so pass it as a named argument:
MobileCredentialHolder.getInstance().initialize(
context = context,
- loggerConfiguration = loggerConfiguration
+ platformConfiguration = PlatformConfiguration(
+ tenantHost = URL("https://your-tenant.vii.mattr.global"),
+ applicationId = "1ef1f867-20b4-48ea-aec1-bea7aff4964c"
+ )
)tenantHost: The URL of your MATTR VII tenant where your holder application is configured.applicationId: TheIDof your holder application.
On first initialization, the SDK registers the app instance with your tenant and obtains a license. Network access is required for registration and license renewal. Refer to the SDK Backend guide for more information.
Configure logging with configureLogger
The loggerConfiguration parameter is removed from initialize. Call
MobileCredentialHolder.configureLogger instead. The SDK produces no logs until configureLogger is
called. The configuration is held in memory and kept when deinitialize is called, so call it once
per process, for example in Application.onCreate:
class WalletApplication : Application() {
override fun onCreate() {
super.onCreate()
MobileCredentialHolder.configureLogger(
this,
LoggerConfiguration(
logLevel = LogLevel.Info,
callbackLogLevel = LogLevel.Error
)
)
}
}Pass a context so the SDK can locate its own log storage. Refer to the
SDK logging guide for more information.
Update LoggerConfiguration, LogLevel, and your log callback
LoggerConfiguration and LogLevel were nested under Logger. They are now top-level types, and
Logger is no longer public. Update your imports:
- import global.mattr.mobilecredential.holder.util.Logger.LoggerConfiguration
- import global.mattr.mobilecredential.holder.util.Logger.LogLevel
+ import global.mattr.mobilecredential.holder.util.LoggerConfiguration
+ import global.mattr.mobilecredential.holder.util.LogLevel
+ import global.mattr.mobilecredential.holder.util.LogEventThe LogLevel constants are renamed from UPPER_CASE to TitleCase, WARN is spelled in full as
Warning, and the redundant ASSERT level is removed:
| v7 | v8 |
|---|---|
OFF | Off |
ASSERT | Removed. Use Off or Error. |
ERROR | Error |
WARN | Warning |
INFO | Info |
DEBUG | Debug |
VERBOSE | Verbose |
LogLevel.priority is no longer public.
logDir is removed from LoggerConfiguration, because the SDK now manages its own log file
location. The log callback now receives a single LogEvent that carries the level, tag,
message, optional throwable, and a timestamp that records when the event was created:
LoggerConfiguration(
- logLevel = LogLevel.DEBUG,
- callbackLogLevel = LogLevel.ERROR,
- logDir = logDirectory,
- callback = { priority, tag, message, throwable ->
- Log.println(priority, tag, message)
- }
+ logLevel = LogLevel.Debug,
+ callbackLogLevel = LogLevel.Error,
+ callback = { event: LogEvent ->
+ Log.e(event.tag, "${event.timestamp} ${event.message}", event.throwable)
+ }
)getLog() now returns a single file that combines the current daily log files, oldest first,
instead of moving the current log file.
Remove logLevel from NfcConfiguration
logLevel is removed from NfcConfiguration. NFC logging is now controlled by configureLogger
like every other log call:
MobileCredentialHolder.Nfc.setNfcConfiguration(
context,
- NfcConfiguration(logLevel = Logger.LogLevel.DEBUG)
+ NfcConfiguration()
)Add Timber to your app if you use it
The SDK no longer includes Timber as a dependency. This only affects your app if it uses Timber for its
own logging. Previously, your app received Timber through the SDK, so it worked without declaring the
dependency. If your app uses Timber, add it to your app's build.gradle:
dependencies {
implementation("com.jakewharton.timber:timber:5.0.1")
}Update RetrieveCredentialResult handling
RetrieveCredentialResult now reports which credential each result relates to:
RetrieveCredentialResult.SuccessaddscredentialBundleIdandcredentialReferenceId.RetrieveCredentialResult.FailureaddscredentialIdentifier, the identifier from the token responseauthorization_detailsthat the failed request used.
These properties are nullable and are declared before the existing properties, so update any code that constructs these classes positionally, for example in tests, or destructures them. Reading properties by name is unaffected:
results.forEach { result ->
when (result) {
- is RetrieveCredentialResult.Success -> {
- val (docType, credentialId) = result
- showIssued(docType, credentialId)
- }
+ is RetrieveCredentialResult.Success ->
+ showIssued(result.docType, result.credentialId, result.credentialBundleId)
is RetrieveCredentialResult.Failure ->
- showFailed(result.docType, result.error)
+ showFailed(result.docType, result.credentialIdentifier, result.error)
}
}Use credentialBundleId to match each issued credential to the claim set it was issued for, and
credentialIdentifier to tell the user which credential could not be issued. Refer to the
claim sets guide for more information.
Update failureType serialization handling
MobileCredentialVerificationResult and TrustedCertificateVerificationResult are now serialized
with the key failureType instead of reason, matching the property name:
{
"verified": false,
- "reason": { "type": "...", "message": "..." }
+ "failureType": { "type": "...", "message": "..." }
}Update any code or backend service that persists or parses these serialized forms.
Read verifier details from VerifiedBy.Certificate
VerifiedBy.Certificate now exposes a single verifierInfo property in place of commonName, so
online presentations report the same verifier details as proximity and Digital Credentials API
presentations:
val verifierLabel = when (val verifiedBy = session.verifiedBy) {
- is VerifiedBy.Certificate -> verifiedBy.commonName
+ is VerifiedBy.Certificate ->
+ verifiedBy.verifierInfo.identityMetadata?.displayName ?: verifiedBy.verifierInfo.commonName
is VerifiedBy.Domain -> verifiedBy.domain
}VerifierInfo now includes optional identityMetadata and authorization properties. Each is
null when the verifier certificate does not include the metadata. This feature is in preview.
The VerifierInfo constructor and copy signatures have changed. Recompile any code that was built
against an earlier SDK version.
Remove references to Verifier-only and internal types
The following types are used only by the Verifier SDK and are removed from the Holder SDK. No Holder SDK API accepts or returns them:
MobileCredentialResponseMobileCredentialPresentationCredentialErrorRevocationStatusListsCacheInfoRevocationStatusListsRefreshResultErrorCode
The following types are no longer part of the public API:
CredentialStatusMobileCredentialStatusCheckFailureTypeStatusListInfoValidityInfoSdkTypeRequestPermissionsActivitySdkTestActivitydocTypeMdl
Remove any references to these types from your app. Other Holder SDK types keep their package names, so no import changes are required.
Update credential offer error handling
discoverCredentialOffer, createAuthorizationSession, and retrieveCredentials now report
credential offer errors consistently:
InvalidCredentialOfferException: The offer contains no supported credentials, the authorization server metadata has no token endpoint, or the issuer or authorization server metadata does not support the offer. Previously, some of these conditions threwFailedToDiscoverCredentialOfferExceptionorFailedToRetrieveCredentialsException.InvalidCredentialOfferExceptionis also thrown when the authorization server supports only wallet attestation and does not advertise ES256 indpop_signing_alg_values_supported. When the authorization server also supports thenoneauthentication method, the SDK usesnoneinstead.FailedToDiscoverCredentialOfferException: The issuer or authorization server metadata cannot be retrieved or read.ConnectivityException: There is a network connection issue.
try {
val offer = holder.discoverCredentialOffer(offerUri)
} catch (e: HolderException.InvalidCredentialOfferException) {
// The wallet cannot accept this offer
} catch (e: HolderException.FailedToDiscoverCredentialOfferException) {
// The issuer metadata could not be retrieved or read
} catch (e: HolderException.ConnectivityException) {
// Ask the user to try again when they are online
}DiscoveredCredentialOffer.tokenEndpointAuthMethodsSupported now lists methods in the order the
authorization server advertises them.
Catch device authentication exceptions directly
The retrieveCredentials methods now throw the following exceptions directly, instead of wrapping
them in FailedToRetrieveCredentialsException:
HolderException.UserAuthenticationOnDeviceNotSetupExceptionHolderException.AuthenticationCanceledExceptionHolderException.UserAuthenticationBiometryLockoutExceptionHolderException.UserAuthenticationExceptionHolderException.DeviceKeyGenerationExceptionHolderException.UserAuthenticationUnrecoverableKeyException
If your app inspects the cause of FailedToRetrieveCredentialsException, catch the specific
exceptions instead:
try {
holder.retrieveCredentials(activity, credentialOffer, clientId)
- } catch (e: HolderException.FailedToRetrieveCredentialsException) {
- if (e.cause is HolderException.UserAuthenticationOnDeviceNotSetupException) {
- promptToSetUpScreenLock()
- }
+ } catch (e: HolderException.UserAuthenticationOnDeviceNotSetupException) {
+ promptToSetUpScreenLock()
+ } catch (e: HolderException.UserAuthenticationBiometryLockoutException) {
+ showBiometricLockoutMessage()
}Also note:
retrieveCredentialsandgenerateDeviceKeynow throwUnsupportedDeviceKeyAuthenticationPolicyExceptionwhen user authentication is set up on the device, but none of the authentication methods required by the device key policy are available. Previously,retrieveCredentialsthrewFailedToRetrieveCredentialsExceptionandgenerateDeviceKeythrewUserAuthenticationOnDeviceNotSetupException.ProximityPresentationSession.sendResponseandOnlinePresentationSession.sendResponsenow throwDeviceKeyAuthenticationPolicyChangedExceptionorMACAuthenticationUnavailableForAuthenticationPolicyinstead ofPresentationNotCreatedException.
Check verifier online presentation requests
Online presentation requests are now validated more strictly. The client_id must be a DNS
hostname. Values that contain an IP address, port, path, user information (@), wildcard, or other
characters that are not valid in a hostname are rejected with
HolderException.InvalidAuthorizationRequestUriException before the user is asked to share any data.
No code change is required in your app. Where possible, make sure the verifiers your wallet interacts with send requests that meet this rule.
Handle the new CredentialUpdated activity log event
CredentialEventType has a new CredentialUpdated value, recorded when a credential is updated and
activity log recording is enabled. ActivityLogCredentialEvent.changeSummary describes the claims,
validity, and branding the update changed. Handle the new value in exhaustive when statements:
val title = when (event.eventType) {
CredentialEventType.CredentialAdded -> "Credential added"
CredentialEventType.CredentialRemoved -> "Credential removed"
+ CredentialEventType.CredentialUpdated -> "Credential updated"
}Review other behavior changes
- Digital Credentials API requests that include
expected_originsare now rejected when the origin of the calling website or app is not in the list. The request fails before the consent screen is shown. addTrustedVerifierCertificatesnow accepts intermediate CA certificates, as well as self-signed root CA certificates.
(Optional) Adopt credential update
We will share a complete guide to using the credential update feature closer to the release.
Use isUpdatable to find out whether a stored credential can be updated, then call
updateCredential:
holder.getCredentials().filter { it.isUpdatable }.forEach { metadata ->
try {
when (holder.updateCredential(metadata.id)) {
CredentialUpdateResult.Updated -> Unit // The stored credential was replaced
CredentialUpdateResult.NoUpdateAvailable -> Unit // The stored credential is current
}
} catch (e: HolderException.CredentialNotUpdatableException) {
// The credential must be issued again
} catch (e: HolderException.FailedToUpdateCredentialException) {
// The update failed for another reason
}
}Credentials issued before this release are not updatable. Issue a credential again to make it eligible for update. Refer to credential update for how issuers enable this feature.
How would you rate this page?
Last updated on