# 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
The SDK is available in Kotlin
and Java
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 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.
⚠️ 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
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 onActivityResult
on 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 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 userExited
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 onError
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 | 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 →