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.

Tap2iD-SDK-iOS on GitHub Latest SDK: v2.3.1
Before you start

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)
01

Swift Package Manager

Add the Tap2iD SDK to your Xcode project using Swift Package Manager.

1

Open Xcode

Launch your project in Xcode.

2

Add Package Dependency

Go to File › Add Package Dependencies… and enter the repository URL below.

Swift Package URL
https://github.com/CredenceID/Tap2iD-VerifierSDK-iOS.git
3

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.

4

Add to Target

Select the Tap2iD-VerifyerSDK-Swift library product and add it to your app target. Import it in code as import Tap2iDVerifierSDK.

ℹ For troubleshooting, see Apple's Adding Package Dependencies to Your App.

Simulator architecture

From 2.0.1 the simulator slice is arm64 only.

MacDevice buildsSimulator builds
Apple Siliconsupportedsupported
Intelsupportednot supported
⚠ On an Intel Mac a simulator build fails to link. Build to a physical device, or use an Apple Silicon Mac. SDK 2.0.0 and earlier shipped a universal simulator slice, so this is a change if you are upgrading.
02

Bluetooth Support

Open your project's Info.plist and add these Bluetooth usage description keys to enable BLE communication.

⚠ All three Bluetooth keys are required. The App Store rejects apps without these descriptions.
Info.plist: Bluetooth Keys
<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>
03

NFC Support

NFC requires both a capability entitlement in Xcode and additional keys in Info.plist.

Enable NFC Capability

1

Open your project in Xcode

Select your project in the navigator and click your app target.

2

Go to Signing & Capabilities

Select the Signing & Capabilities tab in the target editor.

3

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.

Info.plist: NFC Keys
<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>
04

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.

Swift: SDK initialization
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")
    }
}
⚠️ Store your license key in 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.

Swift: Device identifier and SDK version
// 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()
You're all set!
Build and run your project. You can now access all Tap2iD iOS SDK APIs in your application.

Example Usage

Swift: TestSDK.swift
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

Swift: Verification Delegate
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

Swift: NFC External Reader Delegate
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.

Swift: Reading a VerificationResult
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 ?? "-")")
            }
        }
    }
}
⚠ Check 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".
✦ Prefer 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 elements are text, not 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.
ℹ Exporting a result. Both 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.

Swift: refreshConfiguration
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.

⚠ The refreshed profile applies to the next transaction — a verification already in flight is unaffected. The completion is not guaranteed to run on the main thread, so hop to the main queue before touching UI.
ℹ Throws 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.

Swift: PDF417 Verification
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, likelyFraudulent or error
  • nativeVerdict — the classifier's own token, unmapped. Use this when passing the verdict to another system that expects the classifier's vocabulary; verdict is the typed form for display.
  • confidenceLevel — classifier confidence
  • cryptoVerification.checked — whether a signature check was attempted at all; verified — whether it passed. Both false means the barcode carried no verifiable signature, which is not the same as failing one.
  • errors — per-check validation failures
  • fields — disclosed attributes, named per ISO 18013-5, filtered by your VwC profile (an age_over_NN the profile lists on any of its requests is included)
ℹ Profile requirement. To receive 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.
⚠ Errors. 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.
⚠ Removed in 2.0.1 — 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.
Apple Wallet · New in 2.3.0

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:

RequestWhat happensReturned to the app
.display(document:elements:)iOS shows the holder's details; nothing is passed to your appOnly the outcome — approved, rejected or dismissed
.dataThe attributes in your Verify with Credence profile are read and verified like verifyMdocA VerificationResult

Prerequisites

Display requestData request
Apple entitlementidentity.displayidentity.read
Brand ID and Key ID in Verify with Credence—Required
Profile attributes listed in the entitlement—Required
1

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.

2

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.

App.entitlements: Tap to Present ID
<!-- 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>
⚠ Build to a device. Add only what Apple granted: a key or element that is not in your provisioning profile stops the app from signing.
3

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.

4

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 attributedocument-elements entry
given_namegiven-name
family_namefamily-name
birth_datedate-of-birth
age_in_years, age_over_NNage
portraitportrait
sexsex
resident_address, resident_city, resident_state, resident_postal_code, resident_countryaddress
heightheight
weightweight
eye_coloureye-color
hair_colourhair-color
signature_usual_marksignature-usual-mark
nationalitynationality
birth_placeplace-of-birth
issuing_authority, issuing_jurisdiction, issuing_countryissuing-authority
driving_privilegesdriving-privileges
document_numberdocument-number
issue_datedocument-issue-date
expiry_datedocument-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

Swift: isProximityReaderSupported
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

Swift: 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

Swift: 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.

Swift: ProximityReaderDelegate
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:

CodeMeaningWhat to check
132Reader token could not be obtainedNetwork connection and the account's Tap to Present ID setup
133The profile has no driver's licence attribute Tap to Present ID can requestThe profile's org.iso.18013.5.1.mDL attributes
134The profile requests attributes the entitlement does not allowThe message names them; add them to document-elements or remove them from the profile
135The app has no Tap to Present ID data entitlementcom.apple.developer.proximity-reader.identity.read
136The account is not registered with Apple for Tap to Present IDBrand 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.

Migration

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_CODE engagement. They were logged as BARCODE_SCAN, which Verify with Credence showed as "Not Applicable".
  • PDF417 age checks. When a profile lists age_over_NN only on its mDL request, a PDF417 scan now returns that age_over_NN in fields. 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:

Swift: Reading a date element
// 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.connectionTimeout through onVerificationStageError, and writes an error transaction log. Previously a host app calling stopMonitoring() directly could end the transaction with no error reported at all.
  • CoreCredenceErrorStruct.combinedCode is 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 misspelled CREDNCE ID.

Upgrading from 2.0.0

EngagementConfig.pdf417 has been removed. Replace:

Swift: Migrating PDF417 verification
// 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.

Next steps