iOS Verifier SDK v7.0.0 Migration Guide
A guide to migrating to iOS Verifier 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 Verifier SDK v7.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:
Validitynow 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) or Apple Wallet 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. Exported logs are now plaintext, so they are easier to read and attach to a support request. - Encodable revocation status list results:
RevocationStatusListsRefreshResultandRevocationStatusListsCacheInfonow conform toEncodable, so you can store them or send them to your backend.
Breaking Changes
This section outlines the breaking changes introduced in v7.0.0 that require updates to your existing implementation:
| # | Change | Impact |
|---|---|---|
| 1 | The minimum supported iOS version for the SDK framework is now iOS 15 | Raise your app's deployment target to iOS 15 or later. |
| 2 | Validity has a new signed property, and its initializer is now init(signed:validFrom:validUntil:) | Update any code that constructs Validity or decodes stored Validity values. |
| 3 | MobileCredentialPresentation.docType and validityInfo are now optional | Handle nil where your code reads these properties. |
| 4 | The loggerConfiguration parameter is removed from initialize | Call configureLogger instead. |
| 5 | getCurrentLogFilePath() now returns a plaintext log file instead of a JSON array of strings | Update any tooling that parses exported SDK logs. |
| 6 | MobileCredentialVerificationResult and TrustedCertificateVerificationResult are encoded with the key failureType instead of reason | Update any code that persists or parses these serialized forms. |
| 7 | sendProximityPresentationRequest can throw the new ProximityPresentationSessionError.failedToGenerateReaderAuth | Handle the new error case. |
Migration Steps
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.
Update Validity construction and decoding
Validity has a new signed property (Date). It represents the date and time the credential was
signed by the issuer, as defined in the MSO validityInfo. Update any code that constructs
Validity, for example in tests:
- let validity = Validity(validFrom: validFrom, validUntil: validUntil)
+ let validity = Validity(signed: signed, validFrom: validFrom, validUntil: validUntil)You can now check how recently the issuer signed the credential data:
if let validity = presentation.validityInfo,
validity.signed < Date().addingTimeInterval(-90 * 24 * 60 * 60) {
// The credential was signed more than 90 days ago
}Validity requires signed when decoding. Validity values, and the presentation results that
contain them, encoded by an earlier SDK version do not include signed and cannot be decoded by
v7.0.0. If you persist presentation results, plan to migrate or discard them when you upgrade.
Handle optional docType and validityInfo
MobileCredentialPresentation.docType is now MobileCredentialDataTypes.DocType? and
MobileCredentialPresentation.validityInfo is now Validity?. When the MATTR VII tenant returns an
online (app-to-app) or Apple Wallet 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 nil where your code reads these
properties:
for presentation in response.credentials {
- let docType = presentation.docType
- let validUntil = presentation.validityInfo.validUntil
+ let docType = presentation.docType ?? "Unknown document type"
+ let validUntil = presentation.validityInfo?.validUntil
}Configure logging with configureLogger
The loggerConfiguration parameter is removed from initialize. Call configureLogger instead.
The SDK produces no logs until configureLogger is called, so call it before initialize to capture
logs from initialization:
+ MobileCredentialVerifier.shared.configureLogger(
+ LoggerConfiguration(logLevel: .Info)
+ )
try await MobileCredentialVerifier.shared.initialize(
- platformConfiguration: platformConfiguration,
- loggerConfiguration: LoggerConfiguration(logLevel: .Info)
+ platformConfiguration: platformConfiguration
)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() 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 = MobileCredentialVerifier.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.
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.
Handle reader authentication errors
When reader authentication is enabled for your app instance on your MATTR VII tenant, the SDK retrieves a signed configuration and a reader certificate after it initializes, renews them in the background, and uses the certificate to sign proximity presentation requests.
When reader authentication is required and a request cannot be signed,
sendProximityPresentationRequest throws ProximityPresentationSessionError.failedToGenerateReaderAuth.
The request is not sent, and the session stays open:
do {
let response = try await MobileCredentialVerifier.shared.sendProximityPresentationRequest(
request: requests
)
} catch ProximityPresentationSessionError.failedToGenerateReaderAuth(let reason) {
// The request was not sent. The session is still open, so you can retry or terminate it.
}If your code switches exhaustively over ProximityPresentationSessionError, handle the new case.
This feature is in preview. Its behavior and API may change in a future release.
(Optional) Encode revocation status list results
RevocationStatusListsRefreshResult and RevocationStatusListsCacheInfo now conform to Encodable:
let result = try await MobileCredentialVerifier.shared.refreshRevocationStatusLists()
let json = try JSONEncoder().encode(result)RevocationStatusListsCacheInfoencodes as{"nextUpdate"}.RevocationStatusListsRefreshResult.successencodes as{"nextUpdate"}andfailureencodes as{"nextUpdate", "failedLists"}.nextUpdateis omitted when it isnil.
How would you rate this page?
Last updated on