Android SDK - Integration Guide

The following guide provides step-by-step instructions for integrating the HyperKYC Android SDK into your project.

Additional Resource

• Complete Sample Project: A ready to use example project with all the code you need to get started with the Android SDK quickly.

Prerequisites

Before starting the integration, please ensure you meet all the requirements listed in the Prerequisites for Android SDK Integration section.

Integration Steps

The following steps will guide you through implementing the HyperKYC Android SDK in your application:

Step 1: Add the SDK to your Project

Add this to the project level build.gradle:

Java

allprojects {
    repositories {
        google()
        mavenCentral()
        maven(url = "https://s3.ap-south-1.amazonaws.com/hvsdk/android/releases")

    }
}

Step 2: Add the SDK Dependency and Optimize App Size

Add the SDK dependency to your app-level build.gradle, and optionally exclude unused modules to reduce app size:

gradle

implementation("co.hyperverge:hyperkyc:2.0.1") {
    isTransitive = true
     exclude(group = "co.hyperverge", module = "hypersnap-pdf")
    // Exclude in-house face detector (~2.31 MB).
    // SDK will fallback to a lighter detector (~300 KB).
    // exclude(group = "co.hyperverge", module = "face-detection-preview-frame")

    // Exclude document detection (~3.74 MB).
    // exclude(group = "co.hyperverge", module = "hyperdocdetect")
}

Module	Description	Exclusion Impact
face-detection-preview-frame	In-house face detector	Reduces ~2.31 MB, fallback ~300 KB
hyperdocdetect	Document auto-capture/detection	Reduces ~3.17 MB

Important

Only exclude modules if the functionality is not required for your use case.

HyperKYC Dependencies

Understanding the HyperKYC SDK dependencies is crucial for optimizing your app size and ensuring you include only the necessary components for your specific use case. The following breakdown provides detailed information about each dependency and its impact on your application.

HyperKYC dependencies: 11.74 MB

HyperKYC Dependencies:

Module	Size	Mandatory/Optional
co.hyperverge:hyperkyc	3.74 MB	Mandatory
co.hyperverge:hypersnapsdk	1.17 MB	Mandatory
co.hyperverge:hvcamera-sdk	0.17 MB	Mandatory
co.hyperverge:hypervideo	0.06 MB	Optional (If video recording is enabled for face capture)
co.hyperverge:face-detection-preview-frame	2.31 MB	Optional (Will fallback to Google face detector)
co.hyperverge:hyperdocdetect	3.17 MB	Optional (If auto capture is enabled for document capture)
co.hyperverge:crashguardsdk	0.05 MB	Optional (If crash reporting is to be enabled in the SDK)
co.hyperverge:hypersnap-pdf	1.05 MB	Optional

Step 3 (Optional): Prefetch Resources and Configs

To improve performance, prefetch resources and configs configuration before launch:`

Prefetch timing requirement

Call prefetch() well before launch(), not right before it. Calling it immediately before launch() can leave the workflow stuck in a loading state. Prefetch duration depends on network bandwidth; allow enough time for it to complete before the user starts the workflow.

Kotlin

HyperKyc.prefetch(
    <activity-context>, // type: Context
    "<app_id>", // obtain this from the HyperVerge One dashboard
    "<workflowId>" // obtain this from the HyperVerge One dashboard
)

• activity-context: A reference to the current screen (Activity) in your Android app. Each screen has its own context that provides access to screen-specific resources. You can pass this or context as the value for this parameter.
• appId: Your assigned App ID
• workflowId: Name/ID of the workflow configured in the HyperVerge dashboard

Sample:

HyperKyc.prefetch(
    this@SampleActivity, // value for `activity-context` where SampleActivity is any context on the page (activity)
    abc4de, // sample appID
    qnYFM2_10_09_25_02_28_39 // sample workflowID
)

Step 4: Optional Configurations

Create and customize the HypeKYC Andorid SDK configuration to match your specific requirements and workflow needs.

Step 4.1: Create the HyperKYC Config

HyperKYC Android SDK supports two authentication methods for configuration: appID and appKey for straightforward integration, or access tokens for token-based authentication. Both approaches are demonstrated below, with access token generation steps available on the Authentication page.

(Recommended Method) Using Access Tokens

The following integration code creates a configuration instance based on the accessToken.

Kotlin

val hyperKycConfig = HyperKycConfig(
    accessToken = "<Enter_the_access_token>", // refer to the Authentication page
    workFlow = "<Enter_the_workflow_ID>", // obtain this from the HyperVerge dashboard
    transactionId = "<Enter_the_transaction_ID>"
)

(Legacy Method) Using Credentials

The following integration code creates a configuration instance based on the appID and the appKey provided by HyperVerge:

Kotlin

val hyperKycConfig = HyperKycConfig(
    appId = "<Enter_the_application_ID>",
    appKey = "<Enter_the_application_key>",
    workFlow = "<Enter_the_workflow_ID>", 
    transactionId = "<Enter_the_transaction_ID>"
)

where;

• workflowId: Name/ID of the workflow configured in the HyperVerge dashboard. You can select and configure workflows from the workflows tab in your HyperVerge dashboard.
• transactionId: A unique identifier for each customer session or application instance. This helps track and manage individual verification processes. Learn more about transaction ID.

Step 4.2: Customize the Config

List of workflow configuration options in the HyperVerge Android SDK:

a. Set Custom Inputs

• Use the Set Inputs function when your workflow requires any external custom inputs for its functionality.

hyperKycConfig.setInputs(inputs: Map<String, String>)

b. Set Default Language Code

• Provide an alpha 2 language code to the Set Default Language Code function to set a default language for the workflow's user interface.
• The defaultLangCode parameter accepts the language code value as a string datatype (e.g., "en" for English,"vi" for Vietnamese). Pass it to the setDefaultLangCode() function.

hyperKycConfig.setDefaultLangCode(defaultLangCode: String)

c. Set Use Location

Enable the Set Use Location function to mandatorily require users to grant location permission to the SDK. When enabled, the SDK prevents capturing of the user's face or identity document until the location permission is granted and updated correctly to the SDK.

• The useLocation parameter accepts a boolean datatype (true or false). By default, it's set to false (location is optional).
• If set to true, the SDK won't let the user proceed unless location permission is granted and shared correctly.
• If the permission is not provided or updated to the SDK, it throws a 106-PERMISSIONS_ERROR.

hyperKycConfig.setUseLocation(useLocation: Boolean)

d. Cross Platform Resume (CPR)

The CPR functionality allows users to seamlessly resume their workflow journey across platforms by using a consistent uuid.

• Step 1: Generate a random unique ID for any one workflow session, using HyperKyc.createUniqueId().
• Step 2: Pass the generated unique ID from step one to the SDK, using the function:

hyperKycConfig.setUniqueId(uuid: String) // uuid is the generated uniqueId from step one

Parameter Reference

Function	Purpose	Example	Notes
setInputs(inputs: Map<String, Any>)	Pass dynamic inputs	"name" to "sample name"	Pre-fill workflow fields
setUseLocation(useLocation: Boolean)	Request location consent	true	Denial prevents workflow execution
setDefaultLangCode(defaultLangCode: String)	Set default workflow language	"en"	Defaults to first configured language
setUniqueId(uuid: String)	Add unique ID for CPR	"12345-abc"	Used with transactionId for retry flows

Example Usage

The following example demonstrates how to combine both create the HyperKYC config and customizing the configuration steps into a complete implementation:

Kotlin

val hyperKycConfig = HyperKycConfig(
    appId = "<APP_ID>",
    appKey = "<APP_KEY>",
    workflowId = "<WORKFLOW_ID>",
    transactionId = "<TRANSACTION_ID>"
).apply {
    setInputs(hashMapOf("name" to "sample name"))
    setUseLocation(true)             // Ask for location consent
    setDefaultLangCode("en")         // Set default language
    setUniqueId("12345-abc")         // Unique ID for CPR
}

Step 5: Implement a Results Handler

Create a results handler to process the outcome of the workflow. The example below shows how to register a launcher to handle the results from the SDK:

Kotlin

val hyperKycLauncher = registerForActivityResult(HyperKyc.Contract()) { result ->
    // handle result post workflow finish/exit
    when (result.status) {
        "user_cancelled" -> {
            // user cancelled
        }
        "error" -> {
            // failure
        }
        "auto_approved", 
        "auto_declined", 
        "needs_review" -> {
            // workflow success
        }
    }
}

Step 6 (Optional): Implement Real-Time Event Notifications

The real-time event notification system provides immediate insights into user journeys through event-based architecture. These events are triggered when users complete major milestones in their journey, allowing you to track progress and implement trigger-based interventions.

To implement real-time event notifications in your Android app, refer to the Android implementation guide.

Step 7: Launch the SDK

Call the launch method to initiate the SDK workflow:

hyperKycLauncher.launch(hyperKycConfig)

Important

Avoid repeated SDK initialization. Ensure your app prevents multiple button presses or asynchronous triggers to avoid multiple invocations of the SDK.

You are now ready to build and run your Android app!

Your Android application is now successfully integrated with the HyperKYC SDK. You can build and test your application to ensure everything works as expected.

SDK Responses

For detailed information about Android SDK responses, see the SDK Response Documentation.

Error Response Details

The SDK exposes standardized error codes for consistent handling across modules.

Error Code	Error Name	When Thrown	Causes	Error Messages / Examples
101	SDK_CONFIG_ERROR	At workflow start	• appId / appKey / accessToken / workflowId / transactionId empty • Invalid accessToken (Android; iOS/Web TODO) • Invalid defaultLangCode	• appId or appKey cannot be empty • accessToken cannot be empty • invalid accessToken • workflowId cannot be empty • transactionId cannot be empty • defaultLangCode '<lang>' is not supported
102	SDK_INPUT_ERROR	At workflow start	• Keys from inputsRequired missing • Value type mismatch • File path invalid/inaccessible	• value "<inputValue>" for key "<key>" is not of expected type "<type>" • <key1>, <key2> not found in inputs • File <inputValue> is not accessible
103	USER_CANCELLED_ERROR	During workflow	User cancels via back/close	Workflow cancelled by user
104	WORKFLOW_ERROR	During workflow	• Module execution errors (doc/face/API) • Internal Hypersnap errors (initialization, encryption, instructions, session active) • Multiple docs detected	• Multiple documents detected, please try again! • Doc capture failed! • API call failed • Encryption error • Instruction config error
105	SDK_VERSION_ERROR	After workflow config fetch	SDK version not in properties.sdkVersions range	workflow <workflowId> does not support SDK version <actual>. Use SDK from <min> to <max>
106	PERMISSIONS_ERROR	Capture/NFC screens	• Camera/Mic denied • Location denied (if required) • NFC denied	Following permissions not granted by user: <list>
107	HARDWARE_ERROR	When opening camera	Camera init failure	Camera could not be initialised properly. Please try again.
108	GPS_ACCESS_DENIED	Location request	User denies location	GPS access denied by user
109	QR_SCANNER_ERROR	QR scan	QR scanner submodule missing or QR parsing failure	• QR Scanner module not included • QR parsing failed
110	SSL_CONNECT_ERROR	API call	SSL handshake/pinning fails	• Secure connection could not be established • Certificate pinning error
111	NETWORK_ERROR	API call	• No internet • Timeouts • Server errors (4xx / 5xx) • Token expired	• Please check your internet connection • API call failed! • Server busy • Token expired
112	SIGNATURE_FAILED_ERROR	Response validation	Response checksum mismatch	Network tampering detected
113	FACE_NOT_DETECTED_ERROR	Face capture	Face not present / blurry	• Face not detected • Blurry face, please retry
114	DEVICE_ROOTED_ERROR	Device check	Rooted/jailbroken device	Device rooted/jailbroken
115 (iOS only)	SECURITY_ERROR	Secure flows	Screenshot/recording with secure flag enabled	• Screenshot detected • Screen recording detected
117 (Android only)	ACTIVITY_DESTROYED_ERROR	Returning from capture	• Low memory • "Don't keep activities" enabled	Workflow ended because of low memory
118 (Android only)	LOW_STORAGE_ERROR	During video/image storage	Free space < 1 MB	Low storage, cannot continue
119 (Android only)	NFC_INVALID_ERROR	NFC workflow	NFC SDK module missing in app	NFC module not included
120	NFC_UNAVAILABLE_ERROR	Device capability	NFC not supported	NFC not available on device
121	NFC_AUTHENTICATION_ERROR	NFC read	Chip authentication failed	NFC authentication failed
122	NFC_CONNECTION_ERROR	NFC scan	Card disconnected mid-scan	NFC connection error
123	WEB_FORM_ERROR	Web form	• Misconfigured inputs • Unexpected WebSDK crash	• Form config missing • Unexpected web form error
124	BROWSER_NOT_SUPPORTED	Loading in-app browser	Browser missing	No compatible browser installed
125	NFC_INCOMPLETE_SCAN_ERROR	NFC scan	Incomplete chip read (missing DGs)	NFC scan incomplete
126	PRIVACY_CONSENT_DENIED_ERROR	Privacy consent screen	User denies required consent (e.g., BIPA)	User denied Privacy Consent
127	WEBCORE_NOT_SUPPORTED	Using WebCore SDK	Missing device prerequisites: • Play Store missing • Play Services missing • Android WebView disabled/missing	WebCore not supported on this device
140	SDK_INTERNAL_ERROR	Unexpected SDK state	• State file cannot be retrieved • Low memory • "Don't keep activities" enabled	Failed to retrieve state from file