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

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