FAQs & Known issues¶

FAQs¶

Which iOS versions and devices are supported?¶

The SDK supports iOS 16.0 and later on a physical iPhone. NFC is not available on the iOS Simulator or on iPads. See Specifications.

What capabilities and permissions do I need to declare?¶

The NFC flow requires:

The Near Field Communication Tag Reading capability, with the TAG format.
The eMRTD application identifiers in com.apple.developer.nfc.readersession.iso7816.select-identifiers.
An NFCReaderUsageDescription in Info.plist.

No camera permission is needed. See Installation and Specifications.

How do I integrate the SDK?¶

The SDK is integrated using the zipped .xcframework files. Its third-party code, including OpenSSL, is linked inside VeridasNfcSDK.xcframework, so it does not conflict with another OpenSSL version your app may include.

See Installation.

Why does the SDK not start after integration?¶

The most common causes are:

The device has no NFC reader, or the app runs on the Simulator. The SDK finishes with nfcUnavailable.
The NFC capability, the application identifiers or NFCReaderUsageDescription are missing.
A malformed or invalid NfcReadConfiguration. The SDK finishes with configValidationError.
Missing bundled JSON files when loading configuration from the app bundle.

If startup fails, check the error received in onNfcReadFinished(error:), including its info, and any event reported through onNfcReadEvent(event:). See API and Configuration.

How do I start the SDK?¶

The standard flow is:

Create an NfcReadConfiguration.
Optionally set an NfcReadEventsDelegate.
Call NfcRead.start(delegate:configuration:).

See API and Installation for examples.

Can I build the configuration in code instead of JSON?¶

Yes. NfcReadConfiguration is Codable, so it can be:

Built directly in Swift code.
Decoded from a JSON file.

Both approaches are supported. See Installation.

What happens if a configuration field is missing?¶

If a property is omitted, the SDK uses the documented default value for that field.

If a property is present but has an unsupported value, configuration validation fails and the SDK does not start. See Configuration.

Can I skip the document data form?¶

Yes. Provide the document number, the date of birth and the date of expiry in setup.prefill, with the dates in MRZ format yyMMdd. When the three values are valid, the form is skipped and the reading starts right away.

If the prefilled data is wrong, the SDK shows the form so the user can correct it. See prefill.

Why is my prefill ignored?¶

The prefill is only used when the three values are present and valid. The most common cause is the date format: the dates must be six digits in MRZ format yyMMdd (for example "860816"), not 1986-08-16. See prefill.

Why does `keysData` only contain the photos?¶

The SDK only returns the data fields listed in setup.keys. If keys is not set or is empty, keysData carries no text field, only the photos (cut_photo and signature), which are always returned when read. List the fields you need, or pass the nfcKeys returned by the Veridas services. Keys are case-sensitive and an unknown key is ignored. See keys.

Can I read a document using the CAN?¶

No. The iOS SDK opens the chip with the MRZ data (document number, date of birth and date of expiry). The Card Access Number (CAN) is not supported.

Can I customize texts, styles, and media?¶

Yes. The SDK configuration is organized into four top-level areas:

setup
texts
styles
medias

This structure lets you separate behavior, wording, visual customization, and assets. See Customization and Migration guide.

Can I customize the system NFC sheet?¶

Only its message. The sheet is drawn by iOS, so its design cannot be changed, but the message shown at each stage can be set with the actionSheetSubtitle texts. See System NFC sheet texts.

Do I need to provide all texts if I want a custom language?¶

Yes. If you want to support a language other than the built-in defaults, you should provide the full custom texts configuration.

The built-in default languages are Spanish and English. See Configuration and Customization.

Can I hide the instructions screen?¶

Yes, using setup.instructionsShow = false.

However, this is only recommended if your app already explains how to read the document with NFC before the SDK starts. See instructionsShow.

Can I hide the SDK close button?¶

Yes, using setup.closeButtonShow = false.

That said, keeping the built-in close button visible is recommended unless your integration already provides a clear and reliable exit mechanism, such as calling NfcRead.stop(). See closeButtonShow.

How many times can the user retry the reading?¶

By default, the user can retry a failed reading 3 times, so up to 4 attempts in total. Change it with setup.maxRetries. Cancelling the system NFC sheet and wrong document data use a retry too. Sending the app to the background does not. See maxRetries.

Can I trust a result delivered by the SDK?¶

The SDK only delivers results for documents that passed every authenticity check it could perform: Passive Authentication and, when the document supports them, Chip Authentication or Active Authentication. A document that fails any of them is not delivered, and the SDK finishes with the corresponding error.

Check authentication in the result to see which anti-cloning check ran. If both chipAuthentication and activeAuthentication are notPerformed, the document does not support either of them. See Results.

How do I receive SDK lifecycle events?¶

Implement:

NfcReadDelegate for result and lifecycle callbacks.
NfcReadEventsDelegate for optional tracking events through onNfcReadEvent(event:).

See API.

What is the difference between `onNfcReadResults` and `onNfcReadEvent`?¶

onNfcReadResults(results:) provides the final successful SDK result.
onNfcReadEvent(event:) provides intermediate lifecycle and tracking events generated during the flow.

Use onNfcReadResults for business completion logic and onNfcReadEvent for logging, analytics, or debugging. See API.

Known issues¶

The NFC reader may need a few seconds after a failed attempt¶

After a failed or cancelled reading, iOS can take a few seconds to release the NFC reader. During that time, the SDK shows a "Preparing NFC reader..." message and starts the next attempt as soon as the reader is available. This is expected behavior.

Documents that can only be detected through PACE are not supported¶

The SDK detects the chip through the ISO 7816 eMRTD application identifiers. Some documents, such as the French ID card, can only be detected through PACE, so the phone does not detect them and they cannot be read.

Invalid configuration values fail at runtime¶

The SDK validates the received configuration when starting. If a property has an unsupported value, the SDK does not start instead of silently ignoring the issue.

This is expected behavior. Validate custom JSON carefully before shipping it. See Configuration and API.

Hiding instructional UI can reduce usability¶

Disabling elements such as the instructions screen may negatively affect comprehension and accessibility, and increase the number of failed readings.

If these elements are hidden, the host application should provide an equivalent user guidance experience. See Accessibility.