Android Verifier SDK v8.0.0 Migration Guide
A guide to migrating to Android Verifier 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 Verifier SDK v8.0.0, including breaking changes, new features, and migration steps.
Key Features
- Reader authentication (Preview): Your verifier app can sign proximity presentation requests with a reader certificate issued by your MATTR VII tenant. The holder's wallet can then show the user who is asking, and warn about or refuse requests from unknown verifiers. Reader authentication is switched on from your MATTR VII tenant, and no changes to your implementation are required.
- Issuer signing time:
MobileCredentialPresentation.validityInfonow includessigned, the date and time the issuer signed the credential. Use it to reject credentials signed too long ago, or to show when a credential was last issued or updated. - More resilient presentation results: When an online (app-to-app) presentation result omits the document type or validity of a credential, your app still receives the rest of the result.
- Standalone logger configuration: Logging is configured with the new
configureLoggermethod, independently of initialization. You can turn logging on beforeinitializeto capture logs from initialization itself. - Smaller public API: Types that are only used by the Holder SDK, and internal types, are no longer part of the Verifier SDK.
Breaking Changes
This section outlines the breaking changes introduced in v8.0.0 that require updates to your existing implementation:
| # | Change | Impact |
|---|---|---|
| 1 | MobileCredentialPresentation.validityInfo is now the new Validity type, which adds signed, instead of MobileCredentialValidity | Update code that reads validityInfo as MobileCredentialValidity or constructs it. |
| 2 | MobileCredentialPresentation.docType and validityInfo are now nullable | Handle null where your code reads these properties. |
| 3 | The loggerConfiguration parameter is removed from initialize | Call MobileCredentialVerifier.configureLogger instead. |
| 4 | 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. |
| 5 | The SDK no longer depends on Timber | Add Timber to your app if you use it. |
| 6 | MobileCredentialVerificationResult and TrustedCertificateVerificationResult are serialized with the key failureType instead of reason | Update any code that persists or parses these serialized forms. |
| 7 | Holder-only types and internal types are removed from the Verifier SDK | Remove any references to them. |
| 8 | sendProximityPresentationRequest can throw the new FailedToGenerateReaderAuthException | Handle the new exception. |
Migration Steps
Update validityInfo handling for the new Validity type
MobileCredentialPresentation.validityInfo is now the new Validity type, instead of
MobileCredentialValidity. Validity adds a signed property (Instant). This property
represents the date and time the credential was signed by the issuer, as defined in the MSO
validityInfo.
Update any code that declares validityInfo as MobileCredentialValidity, or constructs it, for
example in tests:
- import global.mattr.mobilecredential.verifier.dto.MobileCredentialValidity
+ import global.mattr.mobilecredential.verifier.dto.Validity
- val validity = MobileCredentialValidity(validFrom, validUntil)
+ val validity = Validity(signed, validFrom, validUntil)You can now check how recently the issuer signed the credential data:
val signed = presentation.validityInfo?.signed
if (signed != null && signed < Clock.System.now() - 90.days) {
// The credential was signed more than 90 days ago
}Handle nullable docType and validityInfo
MobileCredentialPresentation.docType and MobileCredentialPresentation.validityInfo are now
nullable. When the MATTR VII tenant returns an online (app-to-app) presentation result that omits
either value for a credential, your app now receives the full presentation result, including every
other credential in the response. Previously, the whole result failed to decode and was lost.
Proximity presentation results always include both values. Handle null where your code reads these
properties:
response.credentials.forEach { presentation ->
- val docType = presentation.docType
- val validUntil = presentation.validityInfo.validUntil
+ val docType = presentation.docType ?: "Unknown document type"
+ val validUntil = presentation.validityInfo?.validUntil
}Configure logging with configureLogger
The loggerConfiguration parameter is removed from initialize. Call
MobileCredentialVerifier.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:
+ MobileCredentialVerifier.configureLogger(
+ context,
+ LoggerConfiguration(logLevel = LogLevel.Info, callbackLogLevel = LogLevel.Error)
+ )
MobileCredentialVerifier.initialize(
context,
- platformConfiguration,
- loggerConfiguration
+ platformConfiguration
)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.verifier.util.Logger.LoggerConfiguration
- import global.mattr.mobilecredential.verifier.util.Logger.LogLevel
+ import global.mattr.mobilecredential.verifier.util.LoggerConfiguration
+ import global.mattr.mobilecredential.verifier.util.LogLevel
+ import global.mattr.mobilecredential.verifier.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. It no longer requires the SDK to be initialized.
Add Timber to your app if you use it
The SDK no longer depends on Timber. If your app uses Timber and relied on the SDK to include it at
runtime, add the dependency to your app's build.gradle:
dependencies {
implementation("com.jakewharton.timber:timber:5.0.1")
}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.
Remove references to Holder-only and internal types
The following types are used only by the Holder SDK and are removed from the Verifier SDK. No Verifier SDK API accepts or returns them:
MobileCredentialandMobileCredentialMetaDataDeviceKeyPolicyInfo,DeviceKeyAuthenticationInfo, andUserAuthenticationTypeUserAuthenticationBleMode
The following types are no longer part of the public API:
CredentialStatusMobileCredentialStatusCheckFailureTypeStatusListInfoValidityInfoSdkTypeRequestPermissionsActivitySdkTestActivitySdkLifecycledocTypeMdl
The Verifier SDK manifest no longer declares WebCallbackActivity or
PlatformAuthenticationActivity, which the Verifier SDK never launches.
Remove any references to these types from your app. Other Verifier SDK types keep their package names, so no import changes are required.
Handle reader authentication errors
When reader authentication is enabled for your app instance on your MATTR VII tenant, the SDK retrieves a signed configuration when it initializes, obtains a reader certificate, renews both in the background, and uses the certificate to sign proximity presentation requests. Failures to retrieve the configuration or the reader certificate do not cause initialization to fail.
When reader authentication is required and a request cannot be signed,
sendProximityPresentationRequest throws
VerifierException.ProximityPresentationSessionException.FailedToGenerateReaderAuthException. The
request is not sent:
try {
val response = MobileCredentialVerifier.sendProximityPresentationRequest(requests)
} catch (
e: VerifierException.ProximityPresentationSessionException.FailedToGenerateReaderAuthException
) {
// The request was not sent
}If your code uses an exhaustive when over ProximityPresentationSessionException, handle the new
exception.
This feature is in preview. Its behavior and API may change in a future release.
How would you rate this page?
Last updated on