iOS integration guide

Integration at a glance

With this integration you will embed our technology into your own iOS app. Our UX components blend with yours and the user will go through the necessary steps without leaving your app.

On a high level, this integration has three main steps:
• Create a session using the Session API.
• Start the session in your app using the native SDK and the token created in the previous step.
• Use the Session API to retrieve the identity data when the SDK completes.

Note that there is no sandbox environment for testing, instead, integration and testing is done in production.
When you sign up for an account you can use the Developer plan for this.

Step 1 — Create a session

Start by creating a new session from your backend system:
# request curl http://localhost:4000/api/v2/session.create \ -u PUBLIC_KEY:SECRET \ -d @- << EOF { "face_verification": false, "passport_only": false } EOF # response { "id": 123, "token": "i_dI5hs7m...", ... } Optional properties:
• reference — set a reference to connect the session to any arbitrary identifier, such as a user id or a session id from your own system.
• face_verification — set whether face verification is required or not (false by default).
• passport_only — set whether only passports should be accepted, excluding national ID cards (false by default).

Send the token to your application.

Note that a session is intended to be used for a short period of time to handle a single user. Once a session has been used, it should not be used again.

Step 2 — SDK integration on iOS

Download the SDK (Iris.xcframework) for iOS and add it to your Xcode project.
Both Swift and Objective-C are supported. Minimum target iOS 16.0.

To add a framework to an iOS application, follow these steps:
• Open the app's Xcode project or workspace.
• Go to the app target's General configuration page.
• Add Iris.xcframework to Frameworks, Libraries, and Embedded Content.
• Make sure the framework is embedded and signed by the app target.

The app will need the following entitlement:
<key>com.apple.developer.nfc.readersession.formats</key> <array> <string>TAG</string> </array> And the following entries in Info.plist:
<key>NFCReaderUsageDescription</key> <string>For reading and processing passports and ID cards</string> <key>NSCameraUsageDescription</key> <string>For reading and processing passports and ID cards</string> <key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key> <array> <string>A0000002471001</string> </array> Next, import the SDK and set up a session using the token from the previous step. At some point before starting the session, request permission to use the camera (this is not handled by the SDK).

Start the session.
// integration example in Swift import Iris let iris = Iris() iris.start( in: windowScene, token: token, completion: { givenNames, surname, dateOfBirth, nationality, sex, documentNumber, documentType, expiryDate, issuingCountry, issuer, optionalData, optionalData2, portrait, personalNumber, placeOfBirth, chipAuthentication, activeAuthentication, protocol, face in // session was successful }, failure: { error in // handle error, e.g. retry by calling start again }, cancellation: { // cancelled by the user } )

Step 3 — Retrieve identity data

When the SDK completion callback fires, use the Session API to retrieve the identity data in your backend system.
# request curl http://localhost:4000/api/v2/session.get \ -u PUBLIC_KEY:SECRET \ -d @- << EOF { "id": 123 } EOF # response { "state": "COMPLETED", ... "given_names": "John", "surname": "Doe", "nationality": "US", "sex": "MALE", "date_of_birth": "1988-01-01", "personal_number": "...", "place_of_birth": "...", "optional_data": "...", "optional_data2": "...", "document_type": "PASSPORT", "document_number": "31195855", "expiry_date": "2031-01-01", "issuing_country": "US", "issuer": "Department of State, U.S. Government", "portrait": "dGVzdHRlc3R0ZXN0...", "document_integrity_verified": true, "active_authentication": true, "chip_authentication": true, ... } If face verification was required, an additional property will be available; face — containing an image of the user's face.

Available data and metadata

Data and metadata returned by the Session API, available for you to use in your application:

• Created — Timestamp for when the session was created
• Expires — Timestamp for when the session expires
• State — Current session state
• Reference — Your own optional reference for the session
• User IP — IP address observed when the user initiated the verification
• User agent — User agent observed when the user initiated the verification
• Given names — Given names as stated on the passport or ID
• Surname — Surname as stated on the passport or ID
• Nationality — Two-letter ISO 3166 code (e.g. “US”)
• Sex — “MALE”, “FEMALE” or “UNSPECIFIED”
• Date of birth — Formatted as YYYY-MM-DD
• Personal number — Personal number, if present in the document
• Place of birth — Place of birth, if present in the document
• Optional data — Additional personal data, if present in the document
• Optional data 2 — Additional personal data, if present in the document
• Document type — The document type (e.g. “PASSPORT”)
• Document number — Document number as stated on the passport or ID
• Expiry date — Formatted as YYYY-MM-DD
• Issuing country — Two-letter ISO 3166 code (e.g. “US”)
• Issuer — Name of the issuing authority
• Portrait image — High resolution digital image from the passport or ID, base64 encoded PNG
• Document integrity verified — Whether passive authentication verified the document data
• Active authentication — Whether active authentication was supported and verified
• Chip authentication — Whether chip authentication was supported and verified
• DSC — Document signer certificate used to verify the document
• CSCA certificate fingerprint — Fingerprint of the trusted country signing certificate authority certificate
• Face — Image of the user's face (if face verification was required), base64 encoded PNG

Session lifecycle

Possible lifecycle states for a session:

• State CREATED — The session is created
• State INITIATED — The session has been initiated by the user
• State FAILED — The session failed, e.g. because of an NFC read error
• State CANCELLED — The session was cancelled by the user
• State COMPLETED — The session completed successfully