Tap2iD SDK for iOS - Integration
Add the Tap2iD SDK to your iOS project via Swift Package Manager (SPM) using the provided repository URL. Covers mDL and PDF417 barcode verification, and reading IDs in Apple Wallet with Tap to Present ID.
System Requirements
Your development environment must meet these requirements:
- 🍎 Supported iOS Versions: iOS 17.0 and later
- 🔨 Xcode Version: 15.0 or later
- 📱 Hardware Requirements: iPhone 11 or newer with NFC enabled
- 💻 Build machine: Simulator builds require an Apple Silicon Mac (see Simulator architecture)
Swift Package Manager
Add the Tap2iD SDK to your Xcode project using Swift Package Manager.
Open Xcode
Launch your project in Xcode.
Add Package Dependency
Go to File › Add Package Dependencies… and enter the repository URL below.
https://github.com/CredenceID/Tap2iD-VerifierSDK-iOS.git
Specify Version
Choose Exact Version and enter 2.3.1. Pin exactly rather than by range: releases are immutable, so an exact pin makes the binary your app builds against reproducible.
Add to Target
Select the Tap2iD-VerifyerSDK-Swift library product and add it to your app target. Import it in code as import Tap2iDVerifierSDK.
Simulator architecture
From 2.0.1 the simulator slice is arm64 only.
| Mac | Device builds | Simulator builds |
|---|---|---|
| Apple Silicon | supported | supported |
| Intel | supported | not supported |
Bluetooth Support
Open your project's Info.plist and add these Bluetooth usage description keys to enable BLE communication.
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Your app requires Bluetooth access to connect to nearby devices even in the background.</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>Your app needs to advertise and communicate with other Bluetooth devices.</string>
<key>NSBluetoothWhenInUseUsageDescription</key>
<string>Your app requires Bluetooth access to connect to nearby devices while in use.</string>
NFC Support
NFC requires both a capability entitlement in Xcode and additional keys in Info.plist.
Enable NFC Capability
Open your project in Xcode
Select your project in the navigator and click your app target.
Go to Signing & Capabilities
Select the Signing & Capabilities tab in the target editor.
Add Near Field Communication Tag Reading
Click + and search for Near Field Communication Tag Reading, then add it to your target.
Modify Info.plist
Add the NFC usage description and required identifiers to your Info.plist.
<key>NFCReaderUsageDescription</key>
<string>Your app requires NFC access to read mobile identity documents.</string>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
<string>D2760000850101</string>
</array>
<key>com.apple.developer.nfc.readersession.felica.systemcodes</key>
<array>
<string>12FC</string>
</array>
Add your license key
Generate your license key on the Tap2iD SDK License Key page, then pass it into CoreSdkConfig when you initialize the SDK. Do not hard-code the key. Store it in your project's secrets or environment.
let config = CoreSdkConfig(apiKey: "YOUR_API_KEY") // from verify.credenceid.com
Tap2iDVerifySDK.shared.initSdk(config: config) { result in
if result.isValid {
print("SDK ready")
} else {
print(result.error?.localizedDescription ?? "license invalid")
}
}
Secrets.xcconfig or the iOS Keychain. Do not commit it to source control.
Device identifier and SDK version
Provisioning a reader profile in the portal requires this device's identifier. Fetch it once your license key is verified.
// Identifies this device when provisioning a reader profile in the portal.
let deviceId = Tap2iDVerifySDK.shared.getDeviceIdentifier()
// The linked SDK version — worth logging, and worth quoting in a support request.
let version = Tap2iDVerifySDK.shared.getSdkVersion()
Example Usage
import Tap2iDVerifierSDK
class TestSDK {
var delegate: Tap2iDVerifySDKDelegate?
func initSDK(
apiKey: String,
result: @escaping (LicenseKeyVerificationResult) -> Void
) {
let sdkConfig = CoreSdkConfig(apiKey: apiKey)
Tap2iDVerifySDK.shared.initSdk(config: sdkConfig) { licenseResult in
// isValid, expiryDate, profileName, error
result(licenseResult)
}
}
func startQrEngagement(
capturedQr: String,
result: @escaping (Error?) -> Void
) {
let error = Tap2iDVerifySDK.shared.verifyMdoc(
engagementConfig: .qrCode(capturedQr),
delegate: self
)
if let error { result(error) }
}
// PDF417 is verified with verifyPdf417, not verifyMdoc — see
// "Verifying a PDF417 barcode" below.
func startPdf417Verification(
barcode: String,
completion: @escaping (Result<Pdf417VerificationResult, Error>) -> Void
) {
Task {
do {
let request = Pdf417VerificationRequest(pdf417Value: barcode)
let result = try await Tap2iDVerifySDK.shared.verifyPdf417(request: request)
await MainActor.run { completion(.success(result)) }
} catch {
await MainActor.run { completion(.failure(error)) }
}
}
}
func startNativeNfcEngagement(
result: @escaping (Error?) -> Void
) {
let error = Tap2iDVerifySDK.shared.verifyMdoc(
engagementConfig: .nfc,
delegate: self
)
if let error { result(error) }
}
func startExternalNfcReaderEngagement(
readerDelegate: NfcExternalReaderDelegate,
result: @escaping (Error?) -> Void
) {
let error = Tap2iDVerifySDK.shared.verifyMdoc(
engagementConfig: .nfcExternalReader,
delegate: self,
readerDelegate: readerDelegate
)
if let error { result(error) }
}
func stopMonitoring() {
Tap2iDVerifySDK.shared.stopMonitoring()
}
}
Tap2iDVerifySDKDelegate
extension TestSDK: Tap2iDVerifySDKDelegate {
func onVerificationStageStarted(stage: VerificationStage) {
// Handle verification stage start
}
func onVerificationStageError(
stage: VerificationStage?,
error: CoreCredenceErrorStruct?
) {
// Handle verification error
}
func onVerificationStageCompleted(stage: VerificationStage) {
// Handle verification stage completion
}
func onVerificationCompleted(
verificationResult: VerificationResult?
) {
// Handle final verification result
}
}
NfcExternalReaderDelegate
extension TestSDK: NfcExternalReaderDelegate {
func didDetectReaders() {
// External NFC reader detected
}
func didDisconnectFromReader() {
// External reader disconnected
}
func didDetectSmartCard() {
// Smart card detected
}
func didDisconnectFromSmartCard() {
// Smart card disconnected
}
}
Reading the verification result
onVerificationCompleted delivers a VerificationResult. A result carries one entry per document the holder presented, each with its namespaces and their attributes.
func onVerificationCompleted(verificationResult: VerificationResult?) {
guard let result = verificationResult else { return }
// Overall outcome: success, partialSuccess or failure.
print("status: \(result.status.rawValue)")
for document in result.documents {
print("docType: \(document.docType)")
// Whether the credential itself stood up: issuer and device signatures,
// digests, MSO validity and issuer trust, reduced to one verdict.
switch document.authentication.authenticationStatus {
case .success: print("authentication: passed")
case .warning: print("authentication: passed with warnings")
case .failure: print("authentication: failed")
}
for namespace in document.nameSpaces {
for (element, value) in namespace.attributes {
// Ask whether the element was actually returned before reading it.
// An element your profile requested but the holder declined is absent
// here, and requestedAttributeStatus is what tells the two apart.
guard namespace.requestedAttributeStatus[element] == true else { continue }
print("\(element): \(value ?? "-")")
}
}
}
}
requestedAttributeStatus before trusting an attribute. The holder consents per element, so a profile that requests ten elements may return six. Reading attributes alone cannot distinguish "not disclosed" from "disclosed as empty".
authenticationStatus over the individual checks. AuthenticationDetails also exposes security, msoValidity and trust for when you need to explain why a credential failed, but the derived status is what most integrations should branch on. See the API reference for the full model.
Date. From 2.2.0 a date element — birth_date, expiry_date, issue_date and the rest — is the string the wallet sent: "1971-09-01" for a full-date, "2020-05-04T10:30:00Z" for a tdate. Earlier releases returned a Date, which forced a full-date onto midnight UTC and rendered it as 1971-09-01 00:00:00 +0000. If you were casting these with as? Date, that cast now yields nil — read them as String.
VerificationResult and Pdf417VerificationResult provide toJsonString(), which is useful for logging or handing a result to a backend. It renders every value as text, so binary elements such as the portrait do not survive it intact; read those from attributes directly.
Refreshing the reader profile
initSdk fetches the reader profile once. When the profile changes in the portal — a new document type, a different element set — a running app would otherwise keep using the profile it started with until it is relaunched.
Tap2iDVerifySDK.shared.refreshConfiguration { result in
if result.isRefreshed {
print("profile now: \(result.profileName ?? "-")")
} else {
print(result.error?.localizedDescription ?? "refresh failed")
}
}
Call it when your app is told the profile changed — a push notification, or simply when the app returns to the foreground.
ConfigurationRefreshError.sdkNotInitialized if initSdk has not completed.
Verifying a PDF417 barcode
The barcode on the back of a driver's licence is verified with verifyPdf417, which runs the on-device classifier and the jurisdiction signature checks. It is async and returns its result directly — it does not emit VerificationStage callbacks, so this path is independent of Tap2iDVerifySDKDelegate.
func verifyBarcode(_ scanned: String) {
Task {
do {
let request = Pdf417VerificationRequest(pdf417Value: scanned)
let result = try await Tap2iDVerifySDK.shared.verifyPdf417(request: request)
await MainActor.run {
print("verdict: \(result.verdict.rawValue)")
print("confidence: \(result.confidenceLevel)")
print("state: \(result.stateCode ?? "-")")
let crypto = result.cryptoVerification
if crypto.checked {
print("signature (\(crypto.authority)): \(crypto.verified ? "valid" : "invalid")")
} else {
print("no verifiable signature on this barcode")
}
}
} catch {
await MainActor.run { print("failed: \(error.localizedDescription)") }
}
}
}
Reading the result
verdict—authentic,likelyAuthentic,likelyFraudulentorerrornativeVerdict— the classifier's own token, unmapped. Use this when passing the verdict to another system that expects the classifier's vocabulary;verdictis the typed form for display.confidenceLevel— classifier confidencecryptoVerification.checked— whether a signature check was attempted at all;verified— whether it passed. Bothfalsemeans the barcode carried no verifiable signature, which is not the same as failing one.errors— per-check validation failuresfields— disclosed attributes, named per ISO 18013-5, filtered by your VwC profile (anage_over_NNthe profile lists on any of its requests is included)
fields, your VwC profile must include an aamva.pdf417 document request. If the loaded profile has no such request, the SDK throws Pdf417ImplError.noProfileDefined. If no profile is loaded at all, you still receive a verdict and confidence score, but no fields.
verifyPdf417 throws Pdf417ImplError: sdkNotInitialized (init not completed), classificationFailed (classifier could not read the barcode), or noProfileDefined (no aamva.pdf417 document request). It conforms to LocalizedError, so errorDescription, failureReason and recoverySuggestion carry text you can show the operator directly rather than mapping the cases yourself.
EngagementConfig.pdf417(String) no longer exists. If you are upgrading from 2.0.0, replace verifyMdoc(engagementConfig: .pdf417(value), ...) with verifyPdf417(request:). The result type changes from VerificationResult to Pdf417VerificationResult, and results arrive by return value rather than delegate.
Tap to Present ID
From 2.3.0 the SDK can read a driver's licence from Apple Wallet with Apple's Tap to Present ID (the ProximityReader framework). The holder taps their phone on the verifier's iPhone and approves the request; no QR code or NFC engagement is needed.
There are two kinds of request:
| Request | What happens | Returned to the app |
|---|---|---|
| .display(document:elements:) | iOS shows the holder's details; nothing is passed to your app | Only the outcome — approved, rejected or dismissed |
| .data | The attributes in your Verify with Credence profile are read and verified like verifyMdoc | A VerificationResult |
Prerequisites
| Display request | Data request | |
|---|---|---|
| Apple entitlement | identity.display | identity.read |
| Brand ID and Key ID in Verify with Credence | — | Required |
| Profile attributes listed in the entitlement | — | Required |
Get the entitlements from Apple
Tap to Present ID entitlements are granted by Apple. Request them for your app through your Apple Developer account: the display entitlement for display requests, and the read entitlement — with every document element your profile needs (see the mapping table) — for data requests.
Add the entitlements to your app
In Xcode, select your app target → Signing & Capabilities. If the target has no .entitlements file yet, add any capability (for example Near Field Communication Tag Reading) and Xcode creates one. Open the .entitlements file as source code and add the keys Apple granted.
<!-- Display requests -->
<key>com.apple.developer.proximity-reader.identity.display</key>
<true/>
<!-- Data requests -->
<key>com.apple.developer.proximity-reader.identity.read</key>
<dict>
<key>document-types</key>
<array>
<string>drivers-license</string>
</array>
<key>document-elements</key>
<array>
<string>given-name</string>
<string>family-name</string>
<string>date-of-birth</string>
<string>portrait</string>
<!-- every element your profile requests -->
</array>
</dict>
Register with Apple in Verify with Credence (data requests)
Add your Apple Brand ID and Key ID to your account in Verify with Credence. For every data request the SDK fetches a signed reader token from Verify with Credence, so your app holds no key material. Without this, data requests fail with error 136.
Match your profile to the entitlement (data requests)
The SDK requests the org.iso.18013.5.1.mDL attributes in your verification profile. Each one must appear in document-elements. Before contacting Apple, the SDK compares the two and fails with error 134, naming the attributes the entitlement does not allow. Attributes Apple has no element for are skipped and reported as not shared.
Profile attributes and entitlement elements
| Profile attribute | document-elements entry |
|---|---|
| given_name | given-name |
| family_name | family-name |
| birth_date | date-of-birth |
| age_in_years, age_over_NN | age |
| portrait | portrait |
| sex | sex |
| resident_address, resident_city, resident_state, resident_postal_code, resident_country | address |
| height | height |
| weight | weight |
| eye_colour | eye-color |
| hair_colour | hair-color |
| signature_usual_mark | signature-usual-mark |
| nationality | nationality |
| birth_place | place-of-birth |
| issuing_authority, issuing_jurisdiction, issuing_country | issuing-authority |
| driving_privileges | driving-privileges |
| document_number | document-number |
| issue_date | document-issue-date |
| expiry_date | document-expiration-date |
| organ_donor (AAMVA) | organ-donor-status |
| veteran (AAMVA) | veteran-status |
| DHS_compliance (AAMVA) | document-dhs-compliance-status |
| domestic_driving_privileges (AAMVA) | driving-privileges |
Checking support
if Tap2iDVerifySDK.shared.isProximityReaderSupported() {
// show the Tap to Present ID option
}
isProximityReaderSupported() returns whether this device can act as a Tap to Present ID reader. You do not need to import ProximityReader to call it.
Display request
let request = ProximityReaderRequest.display(
document: .driversLicense,
elements: [.givenName, .familyName, .ageAtLeast(21)]
)
if let error = Tap2iDVerifySDK.shared.verifyMdocWithEntitlement(request: request, delegate: self) {
// .sdkNotInitialized — initSdk has not completed
}
Apple allows four display elements: givenName, familyName, age and ageAtLeast(_:). document can also be .nationalIDCard(region:) (iOS 18 and later) or .photoID (iOS 26 and later).
Data request
if let error = Tap2iDVerifySDK.shared.verifyMdocWithEntitlement(request: .data, delegate: self) {
// .sdkNotInitialized — initSdk has not completed
}
You do not pass elements — they come from your verification profile. The response is verified like verifyMdoc: issuer and device signatures, digests, MSO validity and IACA trust. Elements Apple added after the running iOS version (17.2, 26 and 26.4) are skipped on older devices.
ProximityReaderDelegate
All callbacks are delivered on the main thread.
extension TestSDK: ProximityReaderDelegate {
func onProximityReaderStageStarted(stage: ProximityReaderStage) { }
func onProximityReaderStageCompleted(stage: ProximityReaderStage) { }
func onProximityReaderError(stage: ProximityReaderStage?, error: CoreCredenceErrorStruct) {
// error.combinedCode, error.errorMessage
}
// Display requests only.
func onDisplayRequestCompleted(outcome: ProximityDisplayOutcome) { }
// Data requests only.
func onVerificationCompleted(verificationResult: VerificationResult) { }
}
Stages run in order: PREPARE_READER, REQUEST_DOCUMENT, then VALIDATE_RESPONSE for a data request. Transactions are logged to Verify with Credence like any other engagement. A request the holder cancels is not logged.
Errors
Tap to Present ID errors arrive on onProximityReaderError with a Device Engagement code. The data-request setup errors are:
| Code | Meaning | What to check |
|---|---|---|
| 132 | Reader token could not be obtained | Network connection and the account's Tap to Present ID setup |
| 133 | The profile has no driver's licence attribute Tap to Present ID can request | The profile's org.iso.18013.5.1.mDL attributes |
| 134 | The profile requests attributes the entitlement does not allow | The message names them; add them to document-elements or remove them from the profile |
| 135 | The app has no Tap to Present ID data entitlement | com.apple.developer.proximity-reader.identity.read |
| 136 | The account is not registered with Apple for Tap to Present ID | Brand ID and Key ID in Verify with Credence |
Errors from Apple's framework (a cancelled request, an expired session, an unsupported device) use codes 120–131; see the Credential Verification Errors reference.
Upgrading the Tap2iD iOS SDK
Upgrading from 2.2.0
No source changes are needed.
- Tap to Present ID is new — see Tap to Present ID.
- PDF417 transactions are logged with the
QR_CODEengagement. They were logged asBARCODE_SCAN, which Verify with Credence showed as "Not Applicable". - PDF417 age checks. When a profile lists
age_over_NNonly on its mDL request, a PDF417 scan now returns thatage_over_NNinfields. Previously a barcode scan never produced an age result for such a profile.
Upgrading from 2.0.1
Date elements are returned as text. Date elements — birth_date, expiry_date, issue_date and the rest — now come back as the string the wallet sent, rather than as a Date:
// 2.0.1
let dob = attributes["birth_date"] as? Date // 1971-09-01 00:00:00 +0000
// 2.2.0
let dob = attributes["birth_date"] as? String // "1971-09-01"
A full-date carries no time, so returning a Date forced it onto midnight UTC and every consumer rendered the trailing 00:00:00 +0000. A tdate, conversely, would have lost its time if it were reformatted to a day. The original text is faithful to both: "1971-09-01" for a full-date, "2020-05-04T10:30:00Z" for a tdate.
- An element that nests its value under its own name is now read. Some wallets send
{"birth_date": 1004("1971-09-01")}where the bare tagged date belongs. The issuer signs that shape, so it arrives digest-valid and previously failed to parse. The nested value is now unwrapped and read, and a warning is logged when that happens. - Abandoned transactions report a connection timeout. A transaction cancelled or abandoned before it completes now delivers
DataRetrievalError.connectionTimeoutthroughonVerificationStageError, and writes an error transaction log. Previously a host app callingstopMonitoring()directly could end the transaction with no error reported at all. CoreCredenceErrorStruct.combinedCodeis now public. It was internal, so host apps could not read the combined error code off the struct they were handed. No source change is needed — this only widens access.- Eval-mode watermark. It now reads
CREDENCE ID; it was misspelledCREDNCE ID.
Upgrading from 2.0.0
EngagementConfig.pdf417 has been removed. Replace:
// 2.0.0
verifyMdoc(engagementConfig: .pdf417(value), delegate: self)
// 2.0.1
let result = try await Tap2iDVerifySDK.shared.verifyPdf417(
request: Pdf417VerificationRequest(pdf417Value: value)
)
The result type changes from VerificationResult to Pdf417VerificationResult, and results arrive by return value rather than through the delegate. See also the simulator architecture change.