iOS SDK - Integration Guide

This guide provides step-by-step instructions for integrating the HyperKYC iOS 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 iOS SDK quickly.

Prerequisites

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

Integration Steps

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

Step 1: Add the SDK to your Project

Using Swift Package Manager (SPM)

Availability

Swift Package Manager (SPM) support for iOS HyperKYC is available from version 1.0.0 onwards. For earlier versions, use CocoaPods.

1. Open your Xcode project.
2. Go to File > Add Packages
3. Enter the package URL:

https://github.com/hyperverge/hyperkyc-spm.git

4. Choose the version (e.g., x.y.z) and add the package to your app target.

Important

Select the specific version number appropriate for production use. Check the changelogs for the current recommended version.

Usage: Once integrated, import and use the SDK in your Swift code:

Swift

import HyperKYC

// Your HyperKYC implementation here

Using CocoaPods

1. Add this to your project's Podfile:

Ruby

pod 'HyperKYC', 'x.y.z'

Important

Replace 'x.y.z' with the specific version number for production use. Check out the change logs for the current recommended version.

2. Run the following command in your terminal:

Bash

pod install --repo-update

Step 2: Optimise SDK Size

The iOS SDK provides three submodules to help you optimize your app's size and functionality:

Submodule	Description	Size Impact
Core	Minimal version with basic functionality (default till 0.49.0)	~10.38 MB
CrashGuard	Includes crash reporting (default from 0.50.0)	~11.36 MB
DocDetect	Document auto-capture functionality	~19 MB

Available Submodules

Core (default till 0.49.0)

The minimal version with the smallest size impact. Use this when you only need basic functionality without crash reporting or document detection features.

pod 'HyperKYC/Core', 'x.y.z'

CrashGuard (Default from 0.50.0)

Includes crash reporting functionality and is the default subspec from version 0.50.0. If crash reporting is not required for your implementation, please use the Core submodule instead.

pod 'HyperKYC', 'x.y.z'

DocDetect

Use this submodule when document auto-capture functionality needs to be enabled for document capture.

pod 'HyperKYC/DocDetect', 'x.y.z'

Installation

Replace x.y.z with the specific version number you want to use. If no submodule is specified, CrashGuard will be used by default (for versions 0.50.0 and above).

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.

HyperKyc.prefetch("appId", "workflowId")

• appId: Your assigned App ID
• workflowId: Name/ID of the workflow configured in the HyperVerge dashboard

Step 4: Optional Configurations

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

Step 4.1: Create the HyperKYC Config

HyperKYC iOS 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.

Swift

let hyperKYCConfig = HyperKycConfig(
    accessToken: "<Enter_the_access_token>", // refer to the Authentication page
    workflowId: "<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:

Swift

let hyperKYCConfig = HyperKycConfig(
    appId: "<Enter_the_application_ID>",
    appKey: "<Enter_the_application_key>",
    workflowId: "<Enter_the_workflow_ID>", 
    transactionId: "<Enter_the_transaction_ID>"
)

where;

• workflowId: Name/ID of the workflow you're launching. 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 iOS SDK:

a. Set Custom Inputs

• Use the Set Inputs function when your workflow requires an external input for its functionality.

  let customInputs : [String : String] = ["key1" : "value1", "key2" : "value2",...]
  hyperKycConfig.setInputs(inputs: customInputs)

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(language: defaultLangCode)

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)

b. 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: [String: String])	Pass dynamic inputs	["name": "sample name"]	Pre-fill workflow fields
setUseLocation(useLocation: Bool)	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:

Swift

let hyperKYCconfig = HyperKycConfig(
    appId: "<APP_ID>",
    appKey: "<APP_KEY>",
    workflowId: "<WORKFLOW_ID>",
    transactionId: "<TRANSACTION_ID>"
)

    hyperKYCconfig.setInputs(hashMapOf("name" to "sample name"))
    hyperKYCconfig.setUseLocation(true)             // Ask for location consent
    hyperKYCconfig.setDefaultLangCode("en")         // Set default language
    hyperKYCconfig.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:

Swift

let completionHandler :(_ hyperKycResult: HyperKycResult)->Void = {
    hyperKycResult in
		//  Handle hyperKycResult (refer this for more info)
		let status = hyperKycResult.status
    switch status {
    case "auto_approved":
				// workflow successful
        print("workflow successful - auto approved")
    case "auto_declined":
				// workflow successful
        print("workflow successful - auto declined")
    case "needs_review":
				// workflow successful
        print("workflow successful - needs review")
    case "error":
				// failure
        print("failure")
    case "user_cancelled":
				// user cancelled
        print("user cancelled")
    default :
        print("contact HyperVerge for more details")
    }
}

Step 6: Launch the Workflow

Call the launch method to initiate the SDK workflow:

let transactionId = "iOSHKYCSample_" + self.randomString(length: 10)

let hyperKYCConfig = HyperKycConfig(
    appId: "<APP_ID>",
    appKey: "<APP_KEY>",
    workflowId: "workflow-id",
    transactionId: transactionId
)

HyperKyc.launch(self, hyperKycConfig: hyperKYCConfig) { hyperKycResult in
    // Handle the result
}

• transactionId must be unique per session.
• Handles both success (with response) and failure (with error codes).
• In production, prefer token-based authentication instead of embedding appKey.

Important

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

Step 7 (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 iOS app, refer to the iOS implementation guide.

Step 8: Launch the SDK

Call the launch method to initiate the SDK workflow:

HyperKyc.launch(viewController, hyperKycConfig: config, completionHandler)

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

Your iOS 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 iOS SDK responses, see the SDK Response Documentation.

Error Response Details

The iOS SDK normalizes internal errors into standardized error codes.

Code	Error Name	When Thrown	Example
101	SDK_CONFIG_ERROR	Config invalid/missing	appId cannot be empty
102	SDK_INPUT_ERROR	Invalid/missing inputs	missing required input <key>
103	USER_CANCELLED_ERROR	User action	Workflow cancelled by user
104	WORKFLOW_ERROR	Workflow execution/encryption error	Doc capture failed
105	SDK_VERSION_ERROR	Version mismatch	Unsupported SDK version
106	PERMISSIONS_ERROR	Camera/Mic/Location denied	Camera permission denied
107	HARDWARE_ERROR	Device hardware/camera failure	Camera could not be initialised
108	GPS_ACCESS_DENIED	Location denied	GPS access denied
110	SSL_CONNECT_ERROR	SSL handshake/pinning error	Secure connection could not be established
111	NETWORK_ERROR	Connectivity/server errors	Please check your internet connection
112	SIGNATURE_FAILED_ERROR	Response checksum mismatch	Network tampering detected
113	FACE_NOT_DETECTED	No face/blurry face	Face not detected
115	SECURITY_ERROR	Screenshot/recording detected	Screenshot detected
120	NFC_UNAVAILABLE_ERROR	NFC not on device	NFC not available
121	NFC_AUTHENTICATION_ERROR	NFC chip auth failed	NFC authentication failed
122	NFC_CONNECTION_ERROR	NFC card disconnected	NFC connection error
123	FORM_V2_ERROR	Web form error	Invalid web form config
124	BROWSER_NOT_SUPPORTED	Browser missing	No compatible browser installed
125	NFC_INCOMPLETE_SCAN_ERROR	Partial NFC read	NFC scan incomplete
126	PRIVACY_CONSENT_DENIED_ERROR	User denied consent	User denied Privacy Consent
128	SDK_EXIT_ERROR	SDK closed unexpectedly	Workflow exited
141 (Date Format)	DATE_FORMAT_ERROR	Invalid date format	Invalid date format
151	CHECK_SESSION_ERROR	Session validation failed	Check session error