# Overview
This SDK provides a drop-in set of screens and tools for iOS applications to allow the capture of identity document and user videos for the purpose of identity verification or authentication with official identity.
The SDK is built to help you create the best experience for your customers:
- Enhanced UI to guide your customers through the entire video-capturing process
- Modular design to help you seamlessly integrate the video-capturing process into your application flow
- AI assistance to ensure the quality of the captured videos meets the requirement of the ShareID identity verification process, guaranteeing the best success rate
- Auto-capture of the videos from the document and the user to limit the necessay user interactions
- Direct video upload to the ShareID service, to simplify integration
The SDK is available in Swift
and Objective-c
to best meet your needs.
🖋️ Note:
The SDK is only responsible for capturing and uploading videos. You still need to access the ShareID API to create requests and retrieve results.
# SDK languages
The iOS SDKs are available in the languages below:
French
English
Spanish
German
Italian
Romanian
Russian
The SDK uses the phone default language if it matches one of tha available languages. If the phone default language is not handled by ShareID, the language will be set to English.
# Quick Start
# 1. Obtain API Key
ShareID's SDKs use API keys to securely communicate with ShareID's backend. Upon your registration with ShareID, you will receive an email to generate your business Identifier and a Business Secret Key.
Please make sure you store them in a safe and secure place as they are your credentials to access ShareID.
⚠️ Important:
Your crediantials are your responsability. You must never expose them in your frontend.
# 2. Onboarding demand
Step 1: Use your API Key to request one time tokens so that you can securely communicate with ShareID's backend.
Step 2: Using the one time token generated, initiate an onboarding demand using and external id and a callback url.
Step 3: Record the videos on the front-end.
Step 4: Send all the onboarding demand props and metadata to ShareID
Step 5: Retrieve the results and your metadata from the callback url.
🖋️ Note:
Remember that you can use the metadata to pass elements from your backend to your front-end.
# 3. Authentication demand
Step 1: Use your API Key to request one time tokens so that you can securely communicate with ShareID's backend.
Step 2: Using the one time token generated and the user's UUID, initiate an authentication demand.
Step 3: Stream the user video to ShareID's backend through the SDK.
Step 4: Receive authentication results in realtime.
🖋️ Note:
Remember to set callbacks for success and fail attempts.
# Getting started
The SDK supports iOS version 14.0
and above distribution stats (opens new window)
Our configuration is currently set to the following:
Targeted Device Families = iPhone,iPad
iOS Deployment Target = iOS 14.0
# 1. Obtaining Tokens
For security purposes, the ShareID authorization service requires a token per API call. This means that each demand requires a new token. The process for getting tokens is described in the API Reference documentation in the Access Token section
# 2. SDK dependency
There is no dependency to third party libraries.
# 3. App permissions
The SDK uses the device camera. You're required to have the following key in your application's Info.plist
file
The NSCameraUsageDescription
is described below:
<key>NSCameraUsageDescription</key>
<string>Required for document and facial capture</string>
# 4. Starting the flow
Download the SDK and add it into your Frameworks, Libraries, and Embedded Content. Setup as your SDK as Embed & Sign
# 5. Identity verification request
To begin the verification process, you have to create a view controller with createShareIdFlow
method.
Parameter | Format | Comment |
---|---|---|
setOnboardingToken | string | required The token you get through the authentication process |
setCallbackURL | string | required The url where you want to receive ShareID results |
setExternalId | string | optional Your ID if needed |
🖋️ Note:
The externalId is a metadata that will be sent to you within the ShareID results. It is also used by ShareID to provide you with statistics regarding user retry, drop-off or failure.
Use ShareIdBuilder
to start an identity verification request on Swift
:
let shareIdConfig = ShareIdBuilder()
.setOnBoardingToken(token: onBoardingServiceToken)
.setCallbackURL(callbackURL: "callback url is required")
.setExternalId(externalId: "external id is optional")
.builder()
guard let viewController = ShareIdSingleton.shared.createShareIdFlow(with: shareIdConfig)
else {return}
self.present(viewController, animated: true, completion: nil)
Use ShareIdConfig
to start an identity verification request on Objective-c
:
ShareIdConfig *config = [[ShareIdConfig alloc] init];
[config setOnBoardingToken: onBoardingToken];
[config setCallbackURL: @"callback url is required"];
[config setExternalId: @"external id is optional"];
UIViewController *viewController = [[ShareIdSingleton shared] createShareIdFlowWith:config];
[self presentViewController:viewController animated:YES completion:nil];
You have now successfully started the flow.
# 6. Authentication with official identity
This feature is usable on users onboarded through the identity verification request.
If you haven't onboarded your user yet, refer to the documentation Identity Verification Request.
To launch the authentication with official identity process, get a one time token from the authorization service. This token can not be reused for another request. The process for getting tokens is described in the API Reference documentation in the Access Token section
To begin the process, create a view controller with createShareIdLogIn
method.
Parameter | Format | Comment |
---|---|---|
setOnboardingToken | string | required The token you get through the authentication process |
setApplicantID | string | required The UUID that ShareID provided after the user onboarding through the identity verification request |
Use createShareIdLogIn
to start an authentication request on Swift
let shareIdConfig = ShareIdBuilder()
.setOnBoardingToken(token: "On Boarding Token is required")
.setApplicantID(applicantID: "ApplicantID is required")
.builder()
guard let viewController = ShareIdSingleton.shared.createShareIdLogIn(with: shareIdConfig) else {
return
}
self.present(viewController, animated: true, completion: nil)
Use ShareIdConfig
to start an authentication request on Objective-c
ShareIdConfig *config = [[ShareIdConfig alloc] init];
[config setOnBoardingToken:@"On Boarding Token is required"];
[config setApplicantID:@"ApplicantID is required"];
UIViewController *viewController = [[ShareIdSingleton shared] createShareIdLogInWith:config];
[self presentViewController:viewController animated:YES completion:nil];
# Handling callbacks
# Retrieve results
To receive the ShareID results, you have to implement the protocol ShareIdDelegate
into the application:
ShareIdSingleton.shared.addDelegate(delegate: self)
...
func shareIdOnSuccess(result: ShareIdResult) {
presentAlert(withTitle: "ShareId On Success", message: "Oath2 completed feel free to use data from UserInfo")
}
func shareIdOnCancel(cancel: ShareIdExitMessage) {
presentAlert(withTitle: "ShareId On Cancel", message: cancel.description)
}
func shareIdOnException(exception: ShareIdException) {
presentAlert(withTitle: "ShareId On Error", message: exception.description)
}
[[ShareIdSingleton shared] addDelegateWithDelegate:self];
...
- (void)shareIdOnSuccessWithResult:(ShareIdResult * _Nonnull)result {
[self presentAlert:@"ShareId On Success" andMessage:@"Oath2 completed feel free to use data from UserInfo"];
}
- (void)shareIdOnCancelWithCancel:(ShareIdExitMessage * _Nonnull)cancel {
[self presentAlert:@"ShareId On Cancel" andMessage:[cancel description]];
}
- (void)shareIdOnExceptionWithException:(ShareIdException * _Nonnull)exception {
[self presentAlert:@"ShareId On Error" andMessage:[exception description]];
}
# Remove protocol ShareIdDelegate
...
ShareIdSingleton.shared.removeDelegate(delegate: self)
[[ShareIdSingleton shared] removeDelegateWithDelegate:self];
# Flow successfully completed
When the user will successfully complete the flow and the captured videos will be uploaded, the shareIdOnSuccess
method will be invoked.
The ShareIdResult
object does not contain any information about the document nor the user captured during the acquisition phase.
The table below describes the success messages:
Code | Message |
---|---|
201 | User completed the flow. You can create now a check on your backend side |
200 | Applicant authenticated |
# User exited the flow
When the the user will leave the verification flow, the shareidOnCancel
method will provide you with this information.
The ShareIdExitMessage
will contain the error description as described in the table below:
Code | Message |
---|---|
300 | User left the SDK flow without completing it. Some videos may have already been uploaded. |
# Error Message
In case an error accur during the acquisition phase, the shareIdOnException
method will provide you with the necessary information.
The ShareIdException
will contain a code error and a short description as discribed in the table below:
Code | Message |
---|---|
400 | There is no applicant with that id (authentication failed) |
600 | Onboarding Token can not be empty or null. |
601 | Business Token can not be empty or null. |
602 | Something went wrong during the GET of Business Scope, please take a look at Business Token. |
603 | Something went wrong during the creation of on boarding, please take a look at On Boarding Token. |
604 | Something went wrong during the videos upload. |
605 | Callback URL can not be empty or null. |
606 | Applicant ID can not be empty or null. |
666 | Unknown error try to take a look at the logs. |
700 | User has been denied camera access, please ask permission from the application. |
# SDK Customization
ShareID iOS SDKs are built to enable tailor-made customization during integration.
You can customize:
- Colors
- Text size
- Layer Radius
- Fonts
- Text content (Localizations)
In order to add some custom style for Swift please use ShareIdBuilder
class and for Objective-c ShareIdConfig
class.
# Custom color
Name | Description |
---|---|
setShareIdColor | PrimaryPrimary color for button, border color and another components. |
setShareIdColorText | Light color for text. |
setShareIdColorInactive | Color for inactive button. |
setShareIdColorTextAccent | Color for accent text. |
setShareIdColorBackground | Default color for all screen backgrounds. |
# Custom text size
Name | Description |
---|---|
setShareIdTextSizeSmall | Text size for small labels |
setShareIdTextSizeMedium | Text size for medium labels |
setShareIdTextSizeLarge | Text size for large labels |
# Custom layer radius
Name | Description |
---|---|
setShareIdRadiusSmall | Small radius |
setShareIdRadiusMedium | Medium radius |
# Custom fonts
Name | Description |
---|---|
setShareIdFontHeadline1 | Font for large labels |
setShareIdFontHeadline2 | Font for default title |
setShareIdFontTitle | Font for button title |
setShareIdFontSmall | Font for small labels (in general it is used for description) |
⚠️ Important:
When overriding the ressources style, please make sure it applies to all screen sizes and in particular to small screens devices.
# Custom localizations
The wording used in the ShareID SDK is customizable.
You will need to create a localization file into the main application in order to rewrite the localization strings.
The table below describes the list of localization strings and their default values.
Localization Name | Default |
---|---|
general_continue | Continue |
agreement_title | Let’s verify your identity! |
agreement_description | We need to verify your identity before we can complete the onboarding process. Your information will be encrypted and stored securely. |
agreement_agree | I agree to the Terms and Conditions and the Privacy Policy |
tutorial_title_first | Prepare a valid, identity document |
tutorial_title_second | Make videos clear and readable |
tutorial_title_third | Get ready to verify your identity |
tutorial_description_first | Prepare a valid, government issued identity document |
tutorial_description_third | Get ready to take a video selfie |
identity_choose_country | Choose a country |
identity_select_document | Select a government issued identity document |
document_type_ID_card | ID card |
document_type_passport | Passport |
document_type_residence | Residence permit |
document_type_license | Driver’s license |
before_document_title | Get ready to verify your identity |
before_document_description | All process will be captured automatically. Please follow the further instructions. |
document_record_oops | Oops, it seems that you are not showing the right document! |
document_record_try_again | Try again |
document_record_switch_document | Select another document |
document_record_hold_on | Hold on, Please! |
document_record_scanning | Scanning In Progress |
document_record_rock_front | Rock the front of your ID forwards and backwards, to see the hologram |
document_record_rock_back | Rock the back of your ID forwards and backwards, to see the hologram |
hologram_front_title | Hologram ID front check |
hologram_front_description | We need to scan the front of your ID to verify its authenticity |
hologram_back_title | We need to scan the back of your ID to verify its authenticity |
challenge_look_at_the_camera | Look at the camera |
challenge_look_to_your_right | Look to your right |
challenge_look_to_your_left | Look to your left |
challenge_smile | Smile |
challenge_blink | Blink |
challenge_hold_on | Hold on Please! |
challenge_no_action | Oops, it seems that you are not performing the right action! |
challenge_try_again | Try again |
before_face_record_liveness_check | Liveness check |
before_face_record_title | You will now make a video selfie. |
before_face_record_description | This is a liveness test to validate that \nyou’re the owner of the ID." |
summary_thank | Thank you! |
summary_first_message | Your information has been submitted successfully. |
summary_second_message | The verification process can take up to 2 hours. |
summary_third_message | You will receive a confirmation notification shortly. |
summary_submitted | Your information is being submitted … |
summary_return_main_page | Return to main page |
← Android SDK Web SDK →