iOS SDK v2 Integration Guide
iOS Inquiry SDK v2 Integration Guide and Technical Documentation
v1 or v2?
If your Template ID starts with
itmpl_
, you're in the right place. Otherwise, you will want to look at the v1 section. If you are interested in moving to v2, please contact [email protected].
The Persona Inquiry flow lets you securely and seamlessly collect your user's information.
Integration
Integrate the Persona Inquiry flow directly into your iOS app with our native SDK.
To integrate the Persona Inquiry SDK in your iOS app you can use Swift Package Manager, CocoaPods, or download the XCFramework for manual integration or for use with Carthage.
Releases
Watch this repo for new Releases to be notified when new versions of the iOS SDK are available.
Requirements - Make sure the SDK is compatible
Your app needs to support iOS 11.0 or later.
Installation
Install via Swift Package Manager
To install the SDK with Swift Package Manager:
- Select your project’s Swift Packages tab
- Click on the
+
to add a package - Add the repository URL
https://github.com/persona-id/inquiry-ios-2.git
, and click Next - Choose the package options version rule you want to use. We recommend the default (up to next major version), and click Next
- Check that the package is being added to the right target and click Finish.
Install via CocoaPods
To install the SDK with CocoaPods, add PersonaInquirySDK2
as one of your target dependencies in your Podfile
:
source 'https://github.com/CocoaPods/Specs.git'
use_frameworks!
target 'Your Project' do
pod 'PersonaInquirySDK2'
end
Please be sure to run pod update and use pod install --repo-update to ensure you have the most recent version of the SDK installed.
Install via Carthage
Unfortunately Carthage (as of 0.37.0
) does not appear to support framework binaries containing multi-architecture platforms. If you're using Carthage, you can download the pre-built XCFramework and integrate it manually using the steps outlined below.
Manual installation
The SDK is released as an XCFramework which makes manually installing the SDK a straightforward process:
- Go to the Persona Inquiry SDK Releases page
- Find the latest release
- Expand the
Assets
triangle and download thePersonaSDK.xcframework.zip
file - Unarchive the zip file and drag the
Persona2.xcframework
folder into your Xcode project - A dialog prompt will pop up asking to choose options for adding these files. Please ensure that
Destination
hasCopy items if needed
ticked and that it will be added to the correct target. - Click on
Finish
Update your Info.plist
In addition to importing the dependency, you also need to modify your Info.plist
:
- Navigate to your project's settings in Xcode and click the
Info
tab - Add a new "Privacy - Camera Usage Description" (
NSCameraUsageDescription
) entry (if not already present) to enable camera access. - Add a new "Privacy - Photo Library Usage Description" (
NSPhotoLibraryUsageDescription
) entry (if not already present) to enable photo library access.
Privacy Configuration
This SDK collects a user’s IDFV for fraud prevention purposes. In App Store Connect > Your App > App Privacy, if you haven’t already add in a “Device Identifier,” and fill out the questionnaire with the following answers:
- Usage: App Functionality (covers fraud prevention)
- Are the device IDs collected from this app linked to the user’s identity? Yes
- Do you or your third-party partners use device IDs for tracking purposes? No
Usage
Build and Launch the Inquiry
The Persona Inquiry verification flow is initiated with an InquiryConfiguration
. This configuration can be initialized with either Inquiry Template ID, Inquiry Template Version, or Inquiry ID. The other parameters are optional: theme
, referenceId
, accountId
, and environment
(which defaults to .production
).
Please refer to the code sample below and replace TEMPLATE_ID
with your template ID. You can find your template ID on the Persona Dashboard under "Integration".
This starts the Inquiry flow and takes control of the user interface. Once the flow completes the control of the user interface is returned to the app and the appropriate delegate method will be called.
class MyViewController: UIViewController {
// This is hooked up to a button which starts the flow
@IBAction private func buttonTapped(_ sender: UIButton) {
let config = InquiryConfiguration(templateId: "TEMPLATE_ID")
// Create the inquiry with the view controller
// as the delegate and presenter.
Inquiry(config: config, delegate: self).start(from: self)
}
}
Implement the InquiryDelegate for Inquiry's Result
In order to receive the inquiry result, please implement the InquiryDelegate
protocol. For example:
extension MyViewController: InquiryDelegate {
func inquiryComplete(inquiryId: String, status: String, fields: [String : InquiryField]) {
// Inquiry completed
}
func inquiryCanceled(inquiryId: String?, sessionToken: String?) {
// Inquiry cancelled by user
}
func inquiryError(_ error: Error) {
// Inquiry errored
}
}
Inquiry Results
The results of the inquiry are passed back to the InquiryDelegate
, and are as follows
inquiryComplete
— the inquiry completedinquiryCanceled
— the inquiry was cancelled by the userinquiryError
— the inquiry errored
Linking an Inquiry to your Users
To make it easier to find Inquiries in the Persona Dashboard, we recommend passing in your system's user ID for the Inquiry reference ID.
let config = InquiryConfiguration(
templateId: "TEMPLATE_ID",
referenceId: "myUser_123"
)
Pre-writing to the Inquiry
If you want to add extra information to the Inquiry before the user even starts, you can pass them in as fields
.
let config = InquiryConfiguration(
templateId: "TEMPLATE_ID",
fields: [
"name_first": .string("Susan"),
"name_last": .string("Realman")
]
)
Starting/Resuming an Inquiry from ID
When you create an Inquiry on the server, you can pass the Inquiry ID instead of the Template ID.
let config = InquiryConfiguration(
inquiryId: "inq_123456"
)
If the Inquiry has already started, you will need to also pass in the session token.
let config = InquiryConfiguration(
inquiryId: "inq_123456",
sessionToken: "ABD1234567890"
)
Errors
It is rare but, the Persona Inquiry Sdk may encounter a few categories of client side errors that can not be resolved. When unrecoverable errors are encountered, the Persona Inquiry Sdk will log the error to the Inquiry Session and then immediately callback to the main application with a debug description of the error.
The most common reasons the Persona Inquiry Sdk will error include unrecoverable networking errors, misconfigured templates (should only be encountered during development), or failing to establish a connection the the device camera.
The error callback is located on the InquiryDelegate
with the following signature: func inquiryError(_ error: Error)
.
This error object is of public type PersonaError
defined below.
/// Errors that can occur clientside during the inquiry flow which result in the inquiryError callback
public enum PersonaError: Error, CustomDebugStringConvertible {
/// An api error or connectivity error occurred
case networking
/// Failed to get a context to the device camera
case camera
/// Permissions have been denied or incorrectly configured
case permissions
/// The corresponding template is misconfigured
case misconfigured(InquiryConfigurationError)
/// An otherwise unexpected or unhandled error occurred
case other
/// A short debug description for why the persona sdk errored
public var debugDescription: String {
switch self {
case .networking:
return "There was a problem reaching the server."
case .misconfigured(let error):
return error.errorDescription ?? "There was a problem with the template configuration."
case .camera:
return "There was a problem establishing a connection to the camera."
case .permissions:
return "Permissions have been denied or incorrectly configured."
case .other:
return "An otherwise unexpected error occurred."
}
}
}
Configuration errors are described below, this category of errors should only be encountered during development.
/// Client side InquiryConfiguration errors
public enum InquiryConfigurationError: Error {
/// Inquiry Template Id does not match known structure
case invalidTemplateId(String)
/// Inquiry Template Version does not match known structure
case invalidTemplateVersion(String)
/// This version of the SDK does not support Inquiry Template Ids with supplied prefix
case prefixSDKVersionMismatch(String)
/// The template configuration from server was not valid
case serverConfiguration
}
extension InquiryConfigurationError: LocalizedError {
public var errorDescription: String? {
switch self {
case .invalidTemplateId(let templateId):
return "Could not start Inquiry for templateId: \(templateId). Does not match Inquiry Template Id structure."
case .invalidTemplateVersion(let templateVersion):
return "Could not start Inquiry for templateVersion: \(templateVersion). Does not match Inquiry Template Version structure."
case .prefixSDKVersionMismatch(let prefix):
return "Inquiry Template Ids with prefix: \(prefix) are only valid in v1.x.x of SDK."
case .serverConfiguration:
return "There was a problem with the template configuration on the server."
}
}
}
Technical Documentation
If you want to dive right in to the API documentation, you can do so here.
Customization
Make the Persona Inquiry flow look and feel like your app.
Custom Styling
Set your own colors, buttons, fonts and more. First, make an InquiryTheme
object and pass it in to the InquiryConfiguration
. For example:
// Configuration with only a template ID and a theme
var theme = InquiryTheme()
theme.backgroundColor = .systemPurple
theme.bodyTextColor = .white
theme.titleTextColor = .black
let config = InquiryConfiguration(
templateId: "TEMPLATE_ID",
theme: theme
)
Supporting dark mode
The Persona iOS SDK will reflect the UITraitCollection
of the parent application to determine the use of dark mode.
The default colors on InquiryTheme
all initialize via the UIColor.init(dynamicProvider:)
interface. See documentation https://developer.apple.com/documentation/uikit/uicolor/3238041-init for reference.
When overriding colors on InquiryTheme
it is recommended that you initialize with the same dynamic provider interface.
Example
extension UIColor {
/// convenience method to make a UIColor with a dark and light variant
class func makeDynamicColor(light: UIColor, dark: UIColor) -> UIColor {
.init(dynamicProvider: { $0.userInterfaceStyle == .dark ? dark : light })
}
}
var theme = InquiryTheme()
theme.backgroundColor = .makeDynamicColor(light: .white, dark: .black)
Opting out of dark mode
Please refer to https://developer.apple.com/documentation/uikit/appearance_customization/supporting_dark_mode_in_your_interface/choosing_a_specific_interface_style_for_your_ios_app for instructions that suit your application’s needs for opting out of dark mode. You can support dark mode in your application while specifically disabling it for Persona by controlling the overrideUserInterfaceStyle
for the window of the view controller that the inquiry is started from.
Updated about 2 years ago