# 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

Example of SDK screens

The SDK is available in Swiftand Objective-cto 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 Flag French
  • GB Flag English
  • Spanish Flag Spanish
  • German Flag German
  • Italian Flag Italian
  • Romanian Flag Romanian
  • Russian Flag 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.

Request API KEY

⚠️   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.

Request Onbaording demand

🖋️   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.

Request Onbaording demand

🖋️   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 NSCameraUsageDescriptionis 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 createShareIdLogInmethod.

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 ShareIdResultobject 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 ShareIdExitMessagewill 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 shareIdOnExceptionmethod will provide you with the necessary information.
The ShareIdExceptionwill 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