iOS SDK - Quick Start Guide

The following guide helps you integrate the HyperKYC iOS SDK and launch your first workflow in minutes.

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.

Step 1: Add SDK to Your Project

To your project's Podfile:

Podfile

pod 'HyperKYC', '<SDK_VERSION>'

Run the following command in your terminal:

Bash

pod install --repo-update

Or, use Swift Package Manager (SPM): SPM is supported from HyperKYC version 1.0.0 onwards; for earlier versions use CocoaPods.

1. Open your Xcode project and go to File > Add Packages...
2. Enter the package URL: https://github.com/hyperverge/hyperkyc-spm.git
3. Choose the version and add the package to your app target.

Pro-Tip

Replace <SDK_VERSION> with the latest version listed in the iOS SDK Changelog.

Step 2: Initialize and Launch the SDK

Initialize the SDK and launch a verification workflow in your required ViewController class:

Swift

let config = HyperKycConfig(
    accessToken: "<ACCESS_TOKEN>",  // Short-lived token from your backend
    workflowId: "<WORKFLOW_ID>",    // Workflow ID from HyperVerge Dashboard
    transactionId: "<TRANSACTION_ID>" // Unique identifier for this application
)

// Launch the HyperVerge SDK with configuration
HyperKyc.launch(self, hyperKycConfig: config) { hyperKycResult in
    // Log result for debugging
    print("status=\(hyperKycResult.status) code=\(hyperKycResult.code ?? 0) message=\(hyperKycResult.message ?? "")")
    
    // Handle verification outcome
    switch hyperKycResult.status {
    case "auto_approved":
        // All checks passed - update UI, proceed
        print("workflow successful - auto approved")
    case "auto_declined":
        // Verification failed - show rejection UI
        print("workflow successful - auto declined")
    case "needs_review":
        // Ambiguous result - show pending review UI
        print("workflow successful - needs review")
    case "user_cancelled":
        // User exited flow - handle gracefully
        print("user cancelled")
    case "error":
        // Technical failure - show retry option
        print("failure")
    default:
        print("contact HyperVerge for more details")
    }
}

The following table describes each parameter in the configuration:

Parameter	Description	Source
accessToken	Short-lived token from your backend	Generate Access Tokens
workflowId	Workflow identifier	HyperVerge Dashboard
transactionId	Unique session identifier	Generated by your backend

That's it! You've launched your first HyperKYC workflow.

Step 3: Handle Results & Test the Flow

The callback in Step 2 returns one of these statuses:

Status	Description
auto_approved	User verified successfully
auto_declined	Application rejected automatically
needs_review	Flagged for manual review
user_cancelled	User exited before completion
error	SDK or network issue

For detailed response formats, error codes, and field descriptions, see the SDK Response documentation.

Test: Build & run your app, trigger the launcher, complete a sample journey, and check the log output to confirm integration.

Next Steps

Explore advanced capabilities:

• Additional Configurations: See the Integration Guide for detailed configuration options including prefetch, UI customization, language settings, and SDK size optimization.
• Error Codes & Troubleshooting: For detailed error codes and descriptions, see Error Response Details.
• Integrate Results Webhook: Receive backend updates when journeys complete using the Results Webhook API.
• Real-time Event Notifications: Track user progress with Real-time Event Notifications
• Sample Project: Download the iOS Sample Project for a complete working example.

Recommendations

Follow these best practices to ensure a secure and smooth integration:

Important

• Validate camera & microphone permissions before SDK launch (if your workflow requires these)
• Do not send SDK results directly to your backend for decisioning. To avoid potential man‑in‑the‑middle (MITM) attacks, integrate the Results Webhook instead to securely receive verified outcomes from HyperVerge servers.
• Avoid repeated SDK initialization. Ensure your app prevents multiple button presses or asynchronous triggers to avoid multiple invocations of the SDK.