Android Dynamic SDK Integration
Introduction
IDWise dynamic SDK offers more control over the journey and step order, and allows your app to show custom screens between ID verification steps. In this mode you start each step explicitly and your app regains UI control after each one.
Important
Please familiarise yourself with end to end sequence diagram for Dynamic SDK Integration
Starting a new journey in dynamic mode
First ensure you have added the android SDK dependency and initialize the SDK as in Step 1 and Step 2.
Once the SDK is initialized, it becomes ready to start an ID verification journey flow. To commence the flow, articulated below methods are offer by SDK to start the journey in dynamic mode:
IDWise.startDynamicJourney(
context,
"<FLOW_ID>", //Provided by IDWise
"<REFERENCE_NUMBER>",
"en",
journeyCallback,
stepCallback
)
This method takes the following parameters:
Parameter | Description |
---|---|
flowId | (also called Journey Definition ID): This is a unique identifier that identifies your journey flow. IDWise shares this with you when you register to use the IDWise system. |
referenceNo | (Optional) This parameter allows you to attach a unique identifier (such as a reference number) with the user undergoing the current journey. It's beneficial for connecting the journey to the user and/or the application that initiated it. |
locale | (Optional) This refers to the ISO code representing the desired language for the user interface components. Please reach out to IDWise Support for the list of available languages. |
IDWiseSDKCallback | This represents the journey level callbacks which are detailed here. |
IDWiseSDKStepCallback | This represents the step level callbacks which are detailed here. |
Journey Callbacks
This section provides comprehensive details about journey-level callbacks.
val journeyCallback = object : IDWiseSDKCallback {
override fun onJourneyStarted(journeyInfo: JourneyInfo) {
Log.d("IDWiseSDKCallback", "onJourneyStarted")
}
override fun onJourneyCompleted(journeyInfo: JourneyInfo,isSucceeded: Boolean) {
Log.d("IDWiseSDKCallback", "onJourneyCompleted")
}
override fun onJourneyResumed(journeyInfo: JourneyInfo) {
Log.d("IDWiseSDKCallback", "onJourneyResumed")
}
override fun onJourneyCancelled(journeyInfo: JourneyInfo?) {
Log.d("IDWiseSDKCallback", "onJourneyCancelled")
}
override fun onError(error: IDWiseSDKError) {
Log.d("IDWiseSDKCallback", "onError ${error.message}")
}
})
Callback | Description |
---|---|
onJourneyStarted | This event is triggered when a user's journey started. Once this callback is triggered you can start a step. It is advisable to store the journeyId provided by this callback on your backend in order to track the progress of that journey. |
onJourneyResumed | This event is triggered when a user's journey is resumed. Once this callback is triggered you can start not concluded steps. |
onJourneyCompleted | This callback is triggered upon the completion of a user's journey. It signifies that the user has submitted all steps and finished the journey. When this callback is triggered, it indicates that all user data has been submitted. However, the final decision for this submission should be retrieved from IDWise backend. |
onJourneyCancelled | This is applicable for the simple SDK and not applicable for the dynamic SDK. |
onError | This event is invoked when an error occurs at any point during the journey. It allows your application to respond to any unexpected issues, ensuring smooth error handling and user experience. Below are all possible errors. |
Step Callbacks
This section provides comprehensive details about step-level callbacks.
val stepCallback = object : IDWiseSDKStepCallback {
override fun onStepCaptured(stepId: String, bitmap: Bitmap?, croppedBitmap: Bitmap?) {
//This event triggers when User has captured the image from the camera
}
override fun onStepResult(stepId: String, stepResult: StepResult?) {
//This event is triggered when Image processing is completed at the backend.
//stepResult contains the details of the processing output
Log.d("onStepResult", "Step $stepId result!!")
}
override fun onStepConfirmed(stepId: String) {
Log.d("onStepConfirmed", "Step $stepId confirmed!!")
}
override fun onStepCancelled(stepId: String) {
Log.d("onStepCancelled", "Step $stepId cancelled!!")
}
override fun onStepSkipped(stepId: String) {
Log.d("onStepSkipped", "Step $stepId skipped!!")
}
}
Callback | Description |
---|---|
onStepCaptured | This event is triggered when a user captures an image or selects an image from the gallery. The purpose of this method is to handle the captured step images. It is triggered upon the confirmation of each step side. you can subscribe to this callback if you need access to the captured images. |
onStepResult | This event is triggered when step processing is completed and the results are ready. You can subscribe to this callback for the following scenarios: - Check the status of the step to determine whether it passed or failed. If the step failed and is NOT concluded, you can offer the user a retry. - Display the extracted information from the ID to the user for their review.It is advisable to display a waiting screen (e.g., a spinner) once the onStepCaptured callback is triggered and hide it once onStepResult callback is triggered, to give the user impression the step is being processed.Note: This event is triggered only once for each step, considering both the front and back sides. The outcome for both sides can be retrieved from the result of the front side. |
onStepCancelled | This event is triggered when the user cancels the step. The UI control is handed over to your app. |
onStepSkipped | This event is triggered when a step is skipped by calling the IDWise.skipStep(...) method. |
Starting the Steps
To start a specific step in the journey you should follow:
- Call
IDWise.startStep(context, stepId)
orIDWise.startStepFromFileUpload(context, stepId, byteArray)
method insideonJourneyStarted(...)
oronJourneyResumed(...)
where:context
: Activity of FragmentstepId
: ID of the step you want to start. (Will be provided by IDWise for each step)
Note
When using
startStepFromFileUpload
ensure that the byteArray adheres to the requirements specified here
- The following callbacks will be triggered in this order:
onStepCaptured
: This callback is triggered when data is submitted, but processing is not yet complete.onStepResult
: This callback is triggered once the processing of the step is finished. The results you will receive in this callback can be found here.
Skipping the Step
When onJourneyStarted(...)
or onJourneyResumed(...)
are triggered successfully, you can call the IDWise.skipStep(...)
to skip any verification Step. (Added support from version 4.5.9)
IDWise.skipStep(stepId)
This method takes only one parameter:
stepId
: ID of the step you want to skip. (Will be provided by IDWise for each step)
The step events (provided in IDWiseSDKStepCallback parameter provided to startDynamicJourney or resumeDynamicJourney method) will be triggered as step is skipped.
Step Result Payload
The payload of onStepResult
callback has the following information:
Field | Type | Description |
---|---|---|
recognition | DocumentRecognition | Document recognition information |
extractedFields | Map of String and FieldValue | Information extracted from the document such as Name and Birth Date |
hasPassedRules | Boolean | Whether the step passes the validity checks |
isConcluded | Boolean | Whether the user can still retry the step or not |
status | String | Processing status one of (In Progress , Submitted , Not Submitted ) |
errorUserFeedbackCode | String | A code that can be used to indicate the error. All the error feedback codes can be found here. |
errorUserFeedbackDetails | String | details for the error message directed at the user, providing feedback in case an error occurs during the step. |
errorUserFeedbackTitle | String | A title for the error message directed at the user, providing feedback in case an error occurs during the step. |
nfcResult | NFCResult | Result from NFC chip reading |
DocumentRecognition
This object contains the following information related to the scanned document.
Field | Type | Description |
---|---|---|
issuingCountryCode | String | Country of issue as ISO 3166-1 alpha-3 country code |
issuingCountryName | String | Name of country of issue |
documentType | String | Type of the Document, either a Identity Card , Passport , Commercial Licence , Driving Licence , Practice Permit , Residence Permit , Utility Bill , Vehicle Licence , Vaccination Card , Work Permit , Car Registration , Travel Document , Car Ownership , Visa , Vehicle Registration , Proof of Address , Other Forms , Insurance Certificate , Birth Certificate , Registration Certificate , Tax Document , National Insurance Document , Military ID , Voter Card , Archive Only . |
FieldValue
This object has the following properties
Field | Type | Description |
---|---|---|
value | String | The value of the field |
NFCResult
This object contains the following data extracted from the Document via reading the NFC chip
Field | Type | Description |
---|---|---|
facePhoto | Bitmap | Image of the user which is extracted from NFC chip scanning |
extractedFields | Map of String and FieldValue | Information extracted from the NFC chip scanning |
All extractedFields
from the NFC can be found here
NFC Chip Reading
To enable NFC Chip Reading, special configuration need to be carried out. Please get in touch with IDWise Support for more information.
Get Summary of the Verification Journey
You can get the Status of the journey anytime by calling the following function
IDWise.getJourneySummary() { journeySummary, error ->
// journeySummary contains the status of all steps and overall journey status
}
Journey Summary Result
When you are calling getJourneySummary
method, the result callback will return a JourneySummary
object which contains the following information:
Field | Type | Description |
---|---|---|
journeyId | String | A unique identifier for the user journey. |
isCompleted | Boolean | A boolean field that indicates if the journey is completed or not. |
stepSummaries | List of StepSummary | An array of objects that detail the steps the user has gone through in the journey. Each object in this array contains a definition and a result. |
journeyResult | JourneyResult | Result and Status of the verification Journey as described below |
StepSummary
This object contains the following information:
Field | Type | Description |
---|---|---|
definition | StepDefinition | An object that describes the step. |
result | StepResult | An object that contains the result of the step. |
StepDefinition
This object contains the following information:
Field | Type | Description |
---|---|---|
step_id | Int | An identifier for the step within the journey. |
JourneyResult
This object contains the following information:
Field | Type | Description |
---|---|---|
completedSteps | Int | Number of completed steps in the journey |
interimRuleAssessment | InterimRuleAssessment | Enum for the combined Interim rules assessment result [Passed, Failed] |
interimRuleDetails | HashMap<String, RuleDetail> | Hashmap of all the Rules Assessment Results applicable, here can see all available rules. |
Rule Keys:
This table contains all the rule keys that exists in the interimRuleDetails
Rule Key | Description |
---|---|
same_subject | The same person rule key. |
under_age | The under age rule key. |
no_duplicate_applicant | No duplicate applicant rule key |
RuleDetail
This object contains the following information
Field | Type | Description |
---|---|---|
name | String | Name of the Rule |
result | Result of the Rule Assessment | Enum for the combined Interim rules assessment result [Passed , Failed , CouldNotApply ] |
Error Feedbacks
You can access the table of error feedbacks, which includes descriptions for each of the feedback codes on here
Resuming a dynamic journey
IDWise.resumeDynamicJourney(
context,
"<FLOW_ID>", //Provided by IDWise
"<JOURNEY_ID>",
"en",
journeyCallback,
stepCallback
)
This method takes the following parameters:
flowId
: (also called Journey Definition ID): This is a unique identifier that identifies your journey flow. IDWise shares this with you when you register to use IDWise system.journeyId
: This is a unique identifier that identifies your journey and it can be used to resume. This is received in the implementation ofjourneyCallback
interface inonJourneyStarted
method when you started journey first time.locale
: (Optional)This refers to the ISO code representing the desired language for the user interface components. Please reach out to IDWise Support for the list of available languages.IDWiseSDKCallback
: The implementation of the callback is in the preceding section.IDWiseSDKStepCallback
: The implementation of the callback is in the preceding section.
Finishing a dynamic journey
This method is used to finish the ongoing journey, you can call once all the required the steps are concluded.
IDWise.finishDynamicJourney()
The journey events (provided in IDWiseSDKCallback parameter provided to startDynamicJourney or resumeDynamicJourney method) will be triggered as journey is completed.
Unloading the SDK
You can unload the SDK when it is no longer required to free up the resources
IDWise.unloadSDK()
The journey events (provided in IDWiseSDKCallback parameter provided to startDynamicJourney or resumeDynamicJourney method) will be triggered as journey is completed.
Extracted Fields
Field Name | Available from NFC |
---|---|
Full Name | Yes |
First Name | Yes |
Last Name | Yes |
Birth Date | Yes |
Expiry Date | Yes |
Issue Date | Some ID Documents |
Document Number | Yes |
Issuing Authority | Some ID Documents |
Issuing Country | Yes |
Issuing Country Code | Yes |
Machine Readable Zone | Yes |
Machine Readable Zone Type | Yes |
Nationality | Yes |
Nationality Code | Yes |
Personal Number | Some ID Documents |
Sex | Yes |
Sample Project
You can find the sample project for a complete Android Integration in dynamic mode.
Updated about 2 months ago