ShareID Technical Documentation

# Overview

This SDK provides a drop-in set of screens and tools for Android 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 Kotlinand Javato 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 Android 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

Configuration

minSdkVersion = 21

targetSdkVersion = 30

android.useAndroidX=true

The SDK supports API level 21 and above distribution stats (opens new window).

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11 
        targetCompatibility JavaVersion.VERSION_11
    }

# 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

implementation 'com.google.android.gms:play-services-mlkit-face-detection:16.2.0'
implementation 'com.google.mlkit:image-labeling-custom:16.3.1'

# 3. Aapt Options

    aaptOptions {
        noCompress "tflite"
    }

# 4. Proguard Rules

-keep class * extends androidx.lifecycle.ViewModel {
    public *;
    }

-keep class * extends androidx.lifecycle.AndroidViewModel {
    public *;
}

# 5. Starting the flow

Download the ShareID SDK and implement it into build.gradler(name:'shareId', ext 'aar')

# 6. Identity verification request

To launch the identity verification process, get a one time token from the authorization service. This token can not be reused for another request.

Use your token to start ShareIdMainActivity and action ShareIdMainActivity.SHARE_ID_ACTION using the value ShareIdMainActivity.SHARE_ID_SIGN_UP

The table below describes the list of parameters:

Parameter	Format	Comment
SHARE_ID_ONBOARDING_SERVICE_TOKEN	string	required The token you get through the authentication process
SHARE_ID_CALLBACK_URL	string	required The url where you want to receive ShareID results
SHARE_ID_EXTERNAL_ID	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.

Below a Kotlin example:

 
    private val activityResultLauncher: ActivityResultLauncher = registerForActivityResult(StartActivityForResult()) { result: ActivityResult? ->
        if (result != null) {
            onActivityResult(1, result)
        }
    }

    .....
                    
    val intent = Intent(baseContext, ShareIdMainActivity::class.java)
    intent.putExtra(ShareIdMainActivity.SHARE_ID_ACTION, ShareIdMainActivity.SHARE_ID_SIGN_UP)
    intent.putExtra(ShareIdMainActivity.SHARE_ID_ONBOARDING_SERVICE_TOKEN, "on boarding token")
    intent.putExtra(ShareIdMainActivity.SHARE_ID_CALLBACK_URL, "url callback is required")
    intent.putExtra(ShareIdMainActivity.SHARE_ID_EXTERNAL_ID, "external id is optional")
    activityResultLauncher.launch(intent)

Below a Java example:


    private ActivityResultLauncher activityResultLauncher = registerForActivityResult(new ActivityResultContracts.StartActivityForResult(), result -> {
        onActivityResult(1, result);
    });

    .....
    Intent intent = new Intent(getBaseContext(), ShareIdMainActivity.class);
    intent.putExtra(ShareIdMainActivity.SHARE_ID_ACTION,ShareIdMainActivity.SHARE_ID_SIGN_UP);
    intent.putExtra(ShareIdMainActivity.SHARE_ID_ONBOARDING_SERVICE_TOKEN, "on boarding token");
    intent.putExtra(ShareIdMainActivity.SHARE_ID_CALLBACK_URL, "url callback is required")
    intent.putExtra(ShareIdMainActivity.SHARE_ID_EXTERNAL_ID, "external id is optional")
    activityResultLauncher.launch(intent);

You should have successfully launched an identity verification request.

# 7. Authentication with official identity

This feature is usable on users onboarded through the identity verification request. If you haven't onboarded your users 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

Use your token to start ShareIdMainActivity and action ShareIdMainActivity.SHARE_ID_ACTION using the value ShareIdMainActivity.SHARE_ID_LOG_IN

The table below describes the list of parameters:

Parameter	Format	Comment
SHARE_ID_ONBOARDING_SERVICE_TOKEN	string	required The token you get through the authentication process
SHARE_ID_APPLICANT_ID	string	required The UUID that ShareID provided after the user onboarding through the identity verification request

Below a Kotlin example:

    private val activityResultLauncher: ActivityResultLauncher = registerForActivityResult(StartActivityForResult()) { result: ActivityResult? ->
        if (result != null) {
            onActivityResult(1, result)
        }
    }

    .....
                    
    val intent = Intent(baseContext, ShareIdMainActivity::class.java)
    intent.putExtra(ShareIdMainActivity.SHARE_ID_ACTION, ShareIdMainActivity.SHARE_ID_LOG_IN)
    intent.putExtra(ShareIdMainActivity.SHARE_ID_ONBOARDING_SERVICE_TOKEN, "On Boarding Service Token")
    intent.putExtra(ShareIdMainActivity.SHARE_ID_APPLICANT_ID, "Applicant ID")
    activityResultLauncher.launch(intent)

Below a Java example:

    private ActivityResultLauncher activityResultLauncher = registerForActivityResult(new ActivityResultContracts.StartActivityForResult(), result -> {
        onActivityResult(1, result);
    });

    .....
    Intent intent = new Intent(getBaseContext(), ShareIdMainActivity.class);
    intent.putExtra(ShareIdMainActivity.SHARE_ID_ACTION, ShareIdMainActivity.SHARE_ID_LOG_IN);
    intent.putExtra(ShareIdMainActivity.SHARE_ID_ONBOARDING_SERVICE_TOKEN, "On Boarding Service Token");
    intent.putExtra(ShareIdMainActivity.SHARE_ID_APPLICANT_ID, "Applicant ID");
    activityResultLauncher.launch(intent);

You should have successfully launched an authentication with official identity.

# Handling callbacks

# Retrieve results

In order to retrieve ShareID results from the flow, costumize the method onActivityResulton your activity/fragment. You will also need to implement the interface ShareIdResultListner

Below a Kotlin example:


    private fun onActivityResult(requestCode: Int, result: ActivityResult) {
    if (requestCode == 1) 
        ShareId.getInstance().handleActivityResult(result, object : ShareIdResultListener {
        override fun userCompleted(capture: ShareIdResult) {
            Toast.makeText(applicationContext, capture.message, Toast.LENGTH_SHORT).show()
        }

        override fun userExited(exitMessage: ShareIdExitMessage) {
            Toast.makeText(applicationContext, exitMessage.message, Toast.LENGTH_SHORT).show()
        }

        override fun onError(exception: ShareIdException) {
            Toast.makeText(applicationContext, exception.message, Toast.LENGTH_SHORT).show()
        }
    })
}

Below a Java example:


private void onActivityResult(int requestCode, ActivityResult result) {
if (requestCode == 1)
ShareId.getInstance().handleActivityResult(result, new ShareIdResultListener() {
    @Override
    public void userCompleted(ShareIdResult shareIdResult) {
    Toast.makeText(getApplicationContext(), shareIdResult.getMessage(), Toast.LENGTH_LONG).show();
    }

    @Override
    public void userExited(ShareIdExitMessage shareIdExitMessage) {
    Toast.makeText(getApplicationContext(), shareIdExitMessage.getMessage(), Toast.LENGTH_LONG).show();
    }

    @Override
    public void onError(ShareIdException exception) {
    Toast.makeText(getApplicationContext(), exception.getMessage(), Toast.LENGTH_LONG).show();
    }
});
}

# Flow successfully completed

When the user will successfully complete the flow and the captured videos will be uploaded, the userCompleted 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 userExited 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 onErrormethod 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	CallBack URL 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 Onboarding, please take a look at OnBoarding Token.
604	Something went wrong during the upload of the videos.
605	Action can not be empty or null please set if SHARE_ID_SIGN_UP or SHARE_ID_LOG_IN.
606	External id can not be empty or null.
666	Unknown error try to take a look at the logs.
700	User has denied camera access, please ask permission from the application.
[701 ... 724]	Something went wrong during the setting of camera or record buffer.

# SDK customization

ShareID Android 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

The table below describes the customizable color variables used in the SDK:

Color	Description
shareIdColorPrimary	Primary color for button, border color and another components.
shareIdColorText	Light color for text
shareIdColorInactive	Color for inactive button
shareIdColorTextAccent	Color for accent text
shareIdColorBackground	Default color for all screen backgrounds

# Custom style

The table below descrives the customizable ressources.

Style Name	Description
Widget.AppCompat.Button.Primary	Style for the button (active and inactive)
TextAppearance.AppTheme.Headline1	Style for large text description
TextAppearance.AppTheme.Headline2	Style for medium text description
TextAppearance.AppTheme.Title	For small text description and title into another widgets
Widget.CompoundButton.CheckBox	Style for CheckBox widget

⚠️ 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. Within your application, create a string file with the wording that best meet your needs.
The table below describes the list of localization strings and their default values.

Localization Name	Description
agreement_fragment_continue	Continue
agreement_fragment_header	Let's verify your identity!
agreement_fragment_description	We need to verify your identity before we can complete the onboarding process. \n\n Your information will be encrypted and stored securely.
agreement_fragment_check_box_title	I agree to the Terms and Conditions and the Privacy Policy
tutorial_fragment_title_first	Prepare a valid identity document
tutorial_fragment_title_second	Make videos clear and readable
tutorial_fragment_first	Prepare a valid, government issued identity document
tutorial_fragment_second	Make sure you are in a place with enough light
tutorial_fragment_third	Get ready to take a video selfie
identity_fragment_header	Select a government issued identity document
identity_fragment_choose	Choose a country
identity_fragment_doc_id_card	ID card
identity_fragment_doc_passport	Passport
identity_fragment_doc_residence	Residence permit
identity_fragment_doc_driver	Driving license
identity_fragment_doc_social	Social security card
before_fragment_id_verification	Get ready to verify your identity
before_fragment_doc_description	All process will be captured automatically. Please follow the further instructions
before_fragment_description_first	We need to scan the front and back of your ID to verify its authenticity
before_fragment_description_second	Please follow the instructions on the screen
before_fragment_ready	I’m ready
before_fragment_face	Liveness check
before_fragment_face_video_selfie	You will now make a video selfie
before_fragment_face_bottom_description	This is a liveness test to validate that you’re the owner of the ID.
before_dialog_front_description	We need to scan the front of your ID to verify its authenticity
before_dialog_front_hologram	Hologram ID front check
before_dialog_back_hologram	Hologram ID back check
before_dialog_back_description	We need to scan the back of your ID to verify its authenticity
fragment_camera_rock_front	Rock the front of your ID forwards and backwards, to see the hologram
fragment_camera_rock_back	Rock the back of your ID forwards and backwards, to see the hologram
fragment_camera_look	Look at the camera
fragment_camera_look_right	Look to your right
fragment_camera_look_left	Look to your left
fragment_camera_smile	Smile
fragment_camera_blink	Blink
fragment_scanning_in_progress	Scanning in progress
fragment_no_detect_document_title	Oops! it seems that you are not showing the right document.
fragment_no_action_face_detect	Oops! it seems that you are not performing the right action
fragment_no_detect_document_yes	Try again
fragment_no_detect_document_no	Select another document
fragment_summary_thanks	Thank you!
fragment_summary_thank_first	Your information has been submitted successfully.
fragment_summary_thank_second	The verification process can take up to 2 hours.
fragment_summary_thank_third	You will receive a confirmation notification shortly.
fragment_upload_title	Your information is being submitted …
fragment_summary_return	Return to main page

← API Reference iOS SDK →