iOS Holder SDK v7.0.0 Migration Guide
A guide to migrating to iOS Holder SDK v7.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 iOS Holder SDK v7.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. Exported logs are now plaintext, so they are easier to read and attach to a support request. - 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.
- Digital Credentials API reader authentication (Preview): Signed Digital Credentials API requests are authenticated against your trusted verifier certificates, so a website or app can be identified as a trusted verifier.
- Clearer credential offer errors: Offers your wallet cannot accept are now reported separately from temporary network or server problems.
Breaking Changes
This section outlines the breaking changes introduced in v7.0.0 that require updates to your existing implementation:
| # | Change | Impact |
|---|---|---|
| 1 | The SDK Backend is required: the platformConfiguration parameter of initialize is now a required PlatformConfiguration | Create a holder application on your MATTR VII tenant and pass a PlatformConfiguration to initialize. |
| 2 | The minimum supported iOS version for the SDK framework is now iOS 15 | Raise your app's deployment target to iOS 15 or later. |
| 3 | The loggerConfiguration parameter is removed from initialize and initializeAppExtension | Call configureLogger instead. |
| 4 | getCurrentLogFilePath(appGroup:) now returns a plaintext log file instead of a JSON array of strings | Update any tooling that parses exported SDK logs. |
| 5 | deinitialize is now asynchronous | Add await to all call sites. |
| 6 | initializeAppExtension throws MobileCredentialHolderError.invalidLicense when the main app has not registered with the MATTR VII tenant | Make sure the main app initializes the SDK before the app extension does, and handle invalidLicense. |
| 7 | RetrieveCredentialResult cases carry new associated values, and the enum is no longer @frozen | Update pattern matches and add an @unknown default case. |
| 8 | MobileCredentialVerificationResult and TrustedCertificateVerificationResult are encoded with the key failureType instead of reason | Update any code that persists or parses these serialized forms. |
| 9 | OnlinePresentationSession.VerifiedBy.certificate carries a VerifierInfo instead of the common name | Read verifierInfo.commonName instead of the associated String. |
| 10 | DCPresentationSession.verificationResult is replaced by verifierAuthenticationResult (DCVerifierAuthenticationResult), and requestingWebsiteOrigin is non-optional | Update Digital Credentials API consent screens to the new result type. |
| 11 | Credential offer errors are reported more consistently | Catch invalidCredentialOffer for offers your wallet cannot accept. |
| 12 | Online presentation requests are validated more strictly | Requests with malformed or mismatched verifier identifiers now fail with invalidAuthorizationRequestUri. |
| 13 | CredentialEventType has a new credentialUpdated case | Handle the new case in exhaustive switch statements. |
| 14 | deleteCredential no longer throws credentialNotFound for a credential that does not exist | Remove any handling that relies on this error. |
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 iOS.
- Use the Team ID text box to insert your Apple Developer Team ID.
- Use the Bundle ID text box to insert the Bundle ID of your app (must match your Xcode project configuration).
- 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 App Attest checkbox to configure App Attest for this application. If you leave it
unselected, your tenant does not require an attestation but still validates any attestation it
receives against the
productionenvironment, so a build you run from Xcode on a physical device is rejected. Refer to App Attest environment mismatch (iOS) for more information. - Use the App Attest radio button to select Active or Inactive. When active, the app instance must provide a valid App Attest attestation during registration and token renewal. When inactive, an app instance that cannot produce an attestation can register and renew tokens with an authentication assertion instead. Refer to attestation vs assertion fall back for more information.
- Use the App Attest environment radio button to select Development or Production. This must match the environment your build attests against. Select Inactive with Development to accept both builds you run from Xcode on a physical device and iOS Simulator instances.
- 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 a PlatformConfiguration to initialize
The platformConfiguration parameter of initialize is now required. Pass the URL of your MATTR VII
tenant and the ID of your holder application:
- try await MobileCredentialHolder.shared.initialize()
+ let platformConfiguration = PlatformConfiguration(
+ tenantHost: URL(string: "https://your-tenant.vii.mattr.global")!,
+ applicationId: "1ef1f867-20b4-48ea-aec1-bea7aff4964c"
+ )
+ try await MobileCredentialHolder.shared.initialize(
+ platformConfiguration: platformConfiguration
+ )tenantHost: The URL of your MATTR VII tenant. This must be the 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.
Raise your deployment target to iOS 15
The SDK framework now requires iOS 15 or later. Set your app's deployment target to iOS 15 or later in your Xcode project.
Configure logging with configureLogger
The loggerConfiguration parameter is removed from initialize and initializeAppExtension. Call
configureLogger instead. The SDK produces no logs until configureLogger is called, so call it
before initialize to capture logs from initialization:
+ MobileCredentialHolder.shared.configureLogger(
+ LoggerConfiguration(logLevel: .Info)
+ )
try await MobileCredentialHolder.shared.initialize(
- platformConfiguration: platformConfiguration,
- loggerConfiguration: LoggerConfiguration(logLevel: .Info)
+ platformConfiguration: platformConfiguration
)In an app extension, use configureLogger(_:appGroup:):
+ MobileCredentialHolder.shared.configureLogger(
+ LoggerConfiguration(logLevel: .Info),
+ appGroup: "group.com.example.wallet"
+ )
try MobileCredentialHolder.shared.initializeAppExtension(
- appGroup: "group.com.example.wallet",
- loggerConfiguration: LoggerConfiguration(logLevel: .Info)
+ appGroup: "group.com.example.wallet"
)The logger configuration is kept when deinitialize is called. Calling configureLogger again
replaces the previous configuration. LoggerConfiguration and LogLevel are unchanged.
Refer to the SDK logging guide for more information.
Update log export parsing
getCurrentLogFilePath(appGroup:) now returns the path to a plaintext log file with one entry per
line, instead of a JSON array of strings. Log export files created by earlier SDK versions are
deleted when the logger starts.
if let path = MobileCredentialHolder.shared.getCurrentLogFilePath(),
let url = URL(string: path) {
- let data = try Data(contentsOf: url)
- let entries = try JSONDecoder().decode([String].self, from: data)
+ let text = try String(contentsOf: url, encoding: .utf8)
+ let entries = text.split(separator: "\n")
}LogEvent also has a new timestamp property (Date) that records when the event was created, so
your log callback can include it:
let configuration = LoggerConfiguration(
logLevel: .Info,
callbackLogLevel: .Error
) { event in
print("\(event.timestamp) \(event.level) \(event.message)")
}Await deinitialize
deinitialize is now asynchronous. Add await to all call sites and call it from an asynchronous
context:
- MobileCredentialHolder.shared.deinitialize()
+ await MobileCredentialHolder.shared.deinitialize()deinitialize now waits for any updateCredential call that is already in progress to finish before
it closes access to storage.
Initialize the main app before the app extension
initializeAppExtension now throws MobileCredentialHolderError.invalidLicense when the main app has
not registered with your MATTR VII tenant. Previously, if the main app had never stored a platform
configuration, the app extension initialized without a license.
Make sure the main app has initialized the SDK at least once before the app extension is used, and handle the error:
do {
try MobileCredentialHolder.shared.initializeAppExtension(
appGroup: "group.com.example.wallet"
)
} catch MobileCredentialHolderError.invalidLicense {
// Ask the user to open the main app so it can register with the tenant
}Update RetrieveCredentialResult handling
RetrieveCredentialResult now reports which credential each result relates to:
- The
successcase addscredentialReferenceIdandcredentialBundleId. - The
failurecase addscredentialIdentifier, the identifier from the token responseauthorization_detailsthat the failed request used.
These values are optional. RetrieveCredentialResult is also no longer @frozen, so add an
@unknown default case:
for result in results {
switch result {
- case .success(let docType, let credentialId):
+ case .success(let docType, let credentialId, let credentialReferenceId, let credentialBundleId):
showIssued(docType, credentialId)
- case .failure(let docType, let error):
+ case .failure(let docType, let error, let credentialIdentifier):
showFailed(docType, error.type)
+ @unknown default:
+ break
}
}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. When an issuance
returns several credential identifiers and one of them fails, the credentials that were issued
successfully are kept. The encoded representation of RetrieveCredentialResult includes the new
fields when they are present.
Update failureType serialization handling
MobileCredentialVerificationResult and TrustedCertificateVerificationResult are now encoded with
the key failureType instead of reason, matching the property name:
{
"verified": false,
- "reason": { "type": "...", "message": "..." }
+ "failureType": { "type": "...", "message": "..." }
}MobileCredentialVerificationResultstill decodes either key.TrustedCertificateVerificationResultdecodesfailureTypeonly. A stored value encoded withreasondecodes withfailureTypeset tonil.
Update any code or backend service that persists or parses these serialized forms.
Read verifier details from VerifiedBy.certificate
OnlinePresentationSession.VerifiedBy.certificate now carries a VerifierInfo instead of the
trusted certificate's common name, so online presentations report the same verifier details as
proximity and Digital Credentials API presentations:
switch session.verifiedBy {
- case .certificate(let commonName):
- verifierLabel = commonName
+ case .certificate(let verifierInfo):
+ verifierLabel = verifierInfo.identityMetadata?.displayName ?? verifierInfo.commonName
case .domain(let domain):
verifierLabel = domain
}VerifierInfo now includes optional identityMetadata and authorization properties. Each is nil
when the verifier certificate does not include the metadata. This feature is in preview.
Update Digital Credentials API verifier authentication handling
DCPresentationSession.verificationResult (VerifierAuthenticationResult) is replaced by
verifierAuthenticationResult (DCVerifierAuthenticationResult). Signed requests are now
authenticated against your trusted verifier certificates, so a request can be reported as trusted.
Previously, every signed request was reported as untrusted.
trusted(verifierInfo:): The request was signed by a trusted verifier.untrusted(chains:): The request was signed, but no certificate chain could be trusted. Each entry carries the chain and itsVerifierAuthenticationError.unsigned: The request was not signed. This case no longer carries the origin.
requestingWebsiteOrigin is now a non-optional URL:
- switch session.verificationResult {
+ switch session.verifierAuthenticationResult {
case .trusted(let verifierInfo):
showTrusted(verifierInfo.commonName)
- case .untrusted(let x509CertChain, let error):
- showUntrusted(error)
- case .unsigned(let origin):
- showUnsigned(origin ?? session.requestingWebsiteOrigin?.host ?? "Unknown")
+ case .untrusted(let chains):
+ showUntrusted(chains.first?.error)
+ case .unsigned:
+ showUnsigned(session.requestingWebsiteOrigin.host ?? "Unknown")
+ @unknown default:
+ break
}DCVerifierAuthenticationResult conforms to Sendable only. Unlike VerifierAuthenticationResult,
it is not Encodable or Equatable, so update any code that encodes or compares the result.
Also note:
sendResponse(credentialIDs:)throwsDCError.verifierAuthenticationFailedwhen the signature of a trusted request is invalid.- When a request is trusted and uses
readerAuthAll(ISO/IEC 18013-5 DeviceRequest version 1.1), only the documents requested by the authenticated verifier are returned. - An expired verifier leaf certificate is reported as
expiredCertificateinstead offailedToEvaluateTrust.
This feature is in preview. Its API may change in a future release.
Update credential offer error handling
discoverCredentialOffer, createAuthorizationSession, and retrieveCredentials now report
credential offer errors consistently:
invalidCredentialOffer: The offer contains no supported credentials, or the issuer or authorization server metadata does not support the offer. Previously, some of these conditions threwfailedToDiscoverCredentialOffer.failedToDiscoverCredentialOffer: The issuer or authorization server metadata cannot be retrieved or read.connectivityError: There is a network connection issue.
do {
let offer = try await MobileCredentialHolder.shared.discoverCredentialOffer(offerUri)
} catch MobileCredentialHolderError.invalidCredentialOffer(let reason) {
// The wallet cannot accept this offer
} catch MobileCredentialHolderError.failedToDiscoverCredentialOffer(let reason) {
// The issuer metadata could not be retrieved or read
} catch MobileCredentialHolderError.connectivityError(let reason) {
// Ask the user to try again when they are online
}Check verifier online presentation requests
Online presentation requests are now validated more strictly. Requests that fail these checks throw
MobileCredentialHolderError.invalidAuthorizationRequestUri before the user is asked to share any
data:
- The
client_idmust 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. - For signed requests, the
client_idin the signed request must match theclient_idin the request URI. - The
response_urimust usehttps, and its host must equal theclient_id.
No code change is required in your app. Where possible, make sure the verifiers your wallet interacts with send requests that meet these rules.
Handle the new credentialUpdated activity log event
CredentialEventType has a new credentialUpdated case, 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 case in exhaustive switch statements:
switch event.eventType {
case .credentialAdded:
title = "Credential added"
case .credentialRemoved:
title = "Credential removed"
+ case .credentialUpdated:
+ title = "Credential updated"
}Review deleteCredential error handling
deleteCredential(id:) no longer throws MobileCredentialHolderError.credentialNotFound for a
credential that does not exist or was already deleted. The call now succeeds. Remove any logic that
relies on this error to detect a missing credential.
(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(credentialId:):
for metadata in try MobileCredentialHolder.shared.getCredentials() where metadata.isUpdatable {
do {
switch try await MobileCredentialHolder.shared.updateCredential(credentialId: metadata.id) {
case .updated:
break // The stored credential was replaced with the newer version
case .noUpdateAvailable:
break // The issuer confirmed the stored credential is current
@unknown default:
break
}
} catch MobileCredentialHolderError.credentialNotUpdatable {
// The credential must be issued again
} catch MobileCredentialHolderError.failedToUpdateCredential(let message) {
// 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