iOS SDK v1 Integration Guide
iOS Inquiry SDK Integration Guide and Technical Documentation
Looking for v2?
If your Template starts with
tmpl_
, you're on v1.We will stop making updates to v1 on December 31, 2022. You will still be able to create inquiries, but no new features or fixes will be available. We recommend moving to v2 for access to the latest product improvements- please see migration to v2 section or contact [email protected].
Technical Documentation
If you want to dive right in to the API documentation, you can do so here.
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.
Requirements - Make sure the SDK is compatible
Your app needs to support iOS 11.0 or later.
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.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 PersonaInquirySDK
as one of your target dependencies in your Podfile
:
source 'https://github.com/CocoaPods/Specs.git'
use_frameworks!
target 'Your Project' do
pod 'PersonaInquirySDK'
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 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
Persona.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
That's it!
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.
Usage
The Persona Inquiry verification flow is initiated with an InquiryConfiguration
. This configuration can be initialized with either a templateId
or an inquiryId
.
Please refer to the code sample below and replace my_template_id
with your template ID. You can find your template ID on the Persona Dashboard's Integration Section.
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: "my_template_id")
// Create the inquiry with the view controller
// as the delegate and presenter.
Inquiry(config: config, delegate: self).start(from: self)
}
}
// MARK: - Inquiry Delegate Methods
extension MyViewController: InquiryDelegate {
func inquirySuccess(inquiryId: String, attributes: Attributes, relationships: Relationships) {
// ✅ Inquiry succeeded
}
func inquiryCancelled() {
// ⏏️ Inquiry cancelled by user
}
func inquiryFailed(inquiryId: String, attributes: Attributes, relationships: Relationships) {
// ❌ Inquiry failed
}
func inquiryError(_ error: Error) {
// ⚠️ Inquiry errored
}
}
Inquiry Results
The results of the inquiry are passed back to the InquiryDelegate
, and are as follows
inquirySuccess
— the inquiry passedinquiryFailed
— the inquiry failedinquiryCancelled
— the inquiry was cancelled by the userinquiryError
— the inquiry errored
Configuration Options
Some different configuration examples can be found below:
// Configuration with only a template ID
let config = InquiryConfiguration(
templateId: "tmpl_JAZjHuAT738Q63BdgCuEJQre"
)
// Configuration with only a template ID in the sandbox
let config = InquiryConfiguration(
templateId: "tmpl_JAZjHuAT738Q63BdgCuEJQre",
environment: .sandbox
)
// Configuration with a template and reference ID
let config = InquiryConfiguration(
templateId: "tmpl_JAZjHuAT738Q63BdgCuEJQre",
referenceId: "myReference"
)
// Configuration with a template and account ID
let config = InquiryConfiguration(
templateId: "tmpl_JAZjHuAT738Q63BdgCuEJQre",
accountId: "act_W6thEnEU19gphPqq5uTzZ4Y8"
)
// Configuration with only an inquiry ID
let config = InquiryConfiguration(
inquiryId: "inq_JAZjHuAT738Q63BdgCuEJQre",
)
// Configuration with only a template ID and a theme
var theme = InquiryTheme()
theme.backgroundColor = .purple
theme.bodyTextColor = .white
let config = InquiryConfiguration(
templateId: "tmpl_JAZjHuAT738Q63BdgCuEJQre",
theme: theme
)
Customization
Make the Persona Inquiry flow look and feel like your app.
Theming
You can customize visual attributes of the Persona flow by setting the desired attributes on a Theme
object and passing it to InquiryConfiguration
(shown in the last configuration example in the code block above).
Customizable attributes include colors, fonts, text alignments, images, and animations. A list of customizable theme attributes can be found here:https://sdk.withpersona.com/ios/docs/Structs/InquiryTheme.html
Customizing Fonts
In order to specify fonts on iOS, the fonts must be either system fonts or fonts bundled into your application. For a list of system fonts available out of the box, view: https://developer.apple.com/fonts/system-fonts/
Providing a custom font
If you would like to provide your own custom font, add a font file to the Xcode project by following the guide here: https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app.
Then, you can specify your custom font in the Theme object:
/// Creates a UIFont using the embedded font
let customFont: ((Bool, CGFloat) -> UIFont) = { bold, size in
let name = "CustomFontName-".appending(bold ? "Bold" : "Regular")
guard let font = UIFont(name: name, size: size) else {
fatalError("Could not find a font called \(name)")
}
return font
}
var theme = InquiryTheme()
theme.titleTextFont = customFont(true, 26)
theme.bodyTextFont = customFont(false, 18)
theme.buttonFont = customFont(true, 18)
Replacing Strings
You can replace any title, body, or button text by providing your own strings file called Persona.strings
in your app bundle. At runtime, the SDK will use any of the strings found there.
For example:
/*
Persona.strings
*/
"inquiryStartTitle" = "Verify your identity";
"inquiryStartBody" = "Let’s make sure you’re you!";
"inquiryStartButton" = "Get started";
Available String Keys
// Government ID
"governmentIdFailedTitle" = "Couldn’t verify photos";
"governmentIdFailedGenericReason" = "Make sure the ID details are clear to read.";
"governmentIdFailedButton" = "Retry";
"governmentIdStartTitle" = "Upload a photo ID";
"governmentIdStartBody" = "We require a photo of a government ID to verify your identity.";
"governmentIdSubmittingTitle" = "Processing ID";
"governmentIdSubmittingBody" = "This may take a few seconds";
"governmentIdChooseType" = "Choose 1 of the following options";
// Taking Government ID photos
"takeGovIdPhotoHint" = "Take a clear photo of the ID";
"takeGovIdRetakePhotoButtonText" = "Retake";
"takeGovIdReviewBackPhoto" = "Review the back of ID";
"takeGovIdReviewFrontOrBackPhoto" = "Review the ID";
"takeGovIdReviewFrontPhoto" = "Review the front of ID";
"takeGovIdUsePhotoButtonText" = "Looks good";
"takeGovIdReviewPhotoHint" = "Ensure lighting is good and lettering is clear";
"takeGovIdBackPhotoFormat" = "Back of %@";
"takeGovIdFrontPhotoFormat" = "Front of %@";
"takeGovIdGuideHintBackFormat" = "Position the back of the %@ in the frame";
"takeGovIdGuideHintFrontFormat" = "Position the front of the %@ in the frame";
// Selfie
"selfieFailedTitle" = "Something went wrong";
"selfieFailedBody" = "Make sure your face is visible, well lit, and try again.";
"selfieFailedButton" = "Retry";
"selfieStartTitle" = "Take a selfie";
"selfieStartBody" = "Let’s make sure you’re you";
"selfieStartButton" = "Get started";
"selfieSubmittingTitle" = "Processing selfie";
"selfieSubmittingBody" = "This may take a few seconds";
"takeSelfieCenterPhoto" = "Center yourself in the frame.";
"takeSelfieLeftPhoto" = "Look slightly left.";
"takeSelfieRightPhoto" = "Look slightly right.";
// Country selection
"countrySelectTitle" = "What country is your government ID from?";
"countrySelectBody" = "This helps us determine the best way to verify your identity.";
"countrySelectButton" = "Select country";
"countrySelectPickerText" = "Country of government ID";
// Country List
"countryListAllCountries" = "ALL COUNTRIES";
"countryListSuggested" = "SUGGESTED";
"countryListTitle" = "Select country of ID";
// Inquiry Complete
"inquiryCompleteTitle" = "Congratulations, you’re done!";
"inquiryCompleteBody" = "Thanks for verifying your identity.";
"inquiryCompleteButton" = "Done";
// Inquiry Failed
"inquiryFailedTitle" = "Could not verify your identity";
"inquiryFailedBody" = "We were unable to verify your identity.";
"inquiryFailedButton" = "Close";
// Inquiry Start
"inquiryStartTitle" = "Verify your identity";
"inquiryStartBody" = "Let’s make sure you’re you";
"inquiryStartButton" = "Get started";
// Database
"databaseStartTitle" = "Just the basics";
"databaseStartBody" = "Nothing fancy, just a few things to verify your identity.";
"databaseStartButton" = "Continue";
Updated about 1 year ago