Overview | ShareID Technical Documentation

# 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
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.

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

← Android SDK Web SDK →

# Overview

# SDK languages

# Quick Start

# 1. Obtain API Key

# 2. Onboarding demand

# 3. Authentication demand

# Getting started

# 1. Obtaining Tokens

# 2. SDK dependency

# 3. App permissions

# 4. Starting the flow

# 5. Identity verification request

# 6. Authentication with official identity

# Handling callbacks

# Retrieve results

# Remove protocol ShareIdDelegate

# Flow successfully completed

# User exited the flow

# Error Message

# SDK Customization

# Custom color

# Custom text size

# Custom layer radius

# Custom fonts

# Custom localizations

# Remove protocol `ShareIdDelegate`