zkOBS - Open Banking Services

Use Case

This guide provides detailed instructions on how to integrate zkMe’s zkTLS SDK into your Flutter mobile application for secure Open Banking Services (zkOBS) verification. Through Platform Channels, your Flutter app can seamlessly interact with the native zkTLS SDK on Android and iOS platforms, enabling user data authorization and verification without redirection to external browsers or third-party applications.

This integration approach aims to reduce user friction and drop-off while ensuring sensitive data is never exposed to the app. Users generate privacy-preserving cryptographic proofs, making it an ideal solution for mobile-first products that require secure verification with a single cross-platform Flutter codebase.

---

Requirements & Compatibility

Before starting the integration, ensure your development environment meets the following minimum requirements:

Platform	Minimum Supported Version	Target/Distribution
Android	Android 7.0 (API 24)	Android 14 (API 34)
iOS	iOS 13.0	CocoaPods

The SDK is provided as native libraries. It is compatible with all stable Flutter releases that support standard Platform Channels. No additional Flutter-side dependencies are required beyond the services library.

---

Integration Workflow Overview

Integrating the SDK requires platform-specific native integration for Android and iOS:

• Android Native Integration: Configure your Android project to include the SDK and handle calls from Flutter to start the verification process.

• iOS Native Integration: Configure your iOS project to include the SDK and invoke the native zkTLS verification flow from your view controller.

---

Android Native Integration

This section details how to integrate the zkTLS SDK into the Android portion of your Flutter project and implement the Platform Channel handler to respond to calls from Dart.

Step 1. Add Maven Repository

Add a private Maven repository in settings.gradle.kts (or settings.gradle) in the project root directory.

Kotlin

// settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()

        maven {
            url = uri("https://maven.pkg.github.com/zkMeLabs/selvage-verifier-android-sdk")
            credentials {
                username = "GITHUB_OWNER"
                password = "GITHUB_TOKEN"
            }
        }

        // Official Flutter Engine Repository
        maven {
            url = uri("https://storage.googleapis.com/download.flutter.io")
        }
    }
}

Groovy

Step 2. Add Dependencies

Add the SDK dependency in the build.gradle.kts (or build.gradle) file of your app module.

Kotlin

// build.gradle.kts
dependencies {
    implementation("com.zkme.selvage.verifier:selvage-verifier-sdk:1.0.0")
}

Groovy

Note: Click the Sync Now button in Android Studio and wait for the dependency download to complete.

Step 3. Handle Flutter Calls and Start Verification

To start the verification process on Android when triggered from Flutter, add the following code to your MainActivity. This code invokes the native SelvageSdk.startVerification() API and handles verification callbacks, including success, error, and cancellation.

Kotlin

import com.zkme.selvage.verifier.SelvageSdk
import com.zkme.selvage.verifier.SelvageVerificationResult
import com.zkme.selvage.verifier.SelvageVerificationError

class MainActivity : AppCompatActivity() {
    
    private fun startVerification() {
        SelvageSdk.startVerification(
            context = this,
            requestId = "your-request-id",
            appId = "your-app-id",          
            apiKey = "your-api-key",       
            providerId = "your-provider-id",
            callback = object : SelvageSdk.Callback {
                override fun onSuccess(result: SelvageVerificationResult) {
                    // Verification successful
                    Log.d("Selvage", "Verification Successful")
                    Log.d("Selvage", "Session ID: ${result.sessionId}")
                    Log.d("Selvage", "Proofs JSON: ${result.proofsJson}")
                    
                    // Send proofsJson to your backend for verification
                }
                
                override fun onError(error: SelvageVerificationError) {
                    // Verification failed
                    Log.e("Selvage", "Verification Failed: ${error.code} - ${error.message}")
                    Toast.makeText(this@MainActivity, 
                        "Verification Failed: ${error.message}", 
                        Toast.LENGTH_SHORT).show()
                }
                
                override fun onCancelled() {
                    // User canceled verification
                    Log.d("Selvage", "User cancels verification")
                    Toast.makeText(this@MainActivity, 
                        "User cancels verification", 
                        Toast.LENGTH_SHORT).show()
                }
            }
        )
    }
}

Java

API Reference

SelvageSdk

The main entry class of the SDK, providing verification-related methods.

Method: startVerification

Parameters:

Name	Type	Description
context	Context	Android context, typically an Activity.
requestId	String	Unique identifier for this verification request.
appId	String	App ID
apiKey	String	API key
providerId	String	Provider identifier for the verification flow.
callback	SelvageSdk.Callback	Callback used to receive verification results.

Return Value: None.

SelvageSdk.Callback

Verification result callback interface.

Methods:

onSuccess(result: SelvageVerificationResult): Called when the verification flow completes successfully.

• Parameters: result: SelvageVerificationResult : Result object delivered on successful verification.

---

onError(error: SelvageVerificationError): Called when the verification flow fails.

• Parameters: error: SelvageVerificationError: Error object describing the failure.

---

onCancelled(): Called when the user cancels the verification flow.

• Parameters: None.

SelvageVerificationResult

Result object delivered via SelvageSdk.Callback.onSuccess when the verification flow completes successfully.

---

Properties:

Property	Type	Description
sessionId	String	Session ID
proofsJson	String	Proof data in JSON format.

---

Example: Handling a successful verification result

override fun onSuccess(result: SelvageVerificationResult) {
    val sessionId = result.sessionId
    val proofs = result.proofsJson
    // Send proofs to the backend for verification
    sendToBackend(sessionId, proofs)
}

---

iOS Native Integration

Step 1. Podfile Integration

Add the following to your Podfile:

source '<https://github.com/zkMeLabs/zktls-specs.git>'
source '<https://cdn.cocoapods.org/>'

platform :ios, '13.0'
use_frameworks! :linkage => :static

target 'YourApp' do
  pod 'SelvageVerifierSDK', '1.0.0'
end

Step 2. Initial Setup

# 1. Add the private source to the local repository
pod repo add zktls-specs <https://github.com/zkMeLabs/zktls-specs.git >

# 2. Update the source
pod repo update zktls-specs

# 3. Install Pods
pod install

Step 3. iOS Configuration

3.1 Info.plist

Ensure the following network security configuration is included in your Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

3.2 Build Settings

In your Xcode project’s Build Settings, configure the following:

Setting	Value	Description
Enable Bitcode	No	Flutter does not support Bitcode.
Build Active Architecture Only	Debug: Yes, Release: No	Ensure Release builds include all architectures.
Excluded Architectures (Debug)	i386	Exclude 32-bit emulator architectures.

Step 4. Start Verification on iOS

Swift

import UIKit
import SelvageVerifierSDK

class ViewController: UIViewController {
    
    @IBAction func startVerificationTapped(_ sender: UIButton) {
        startVerification()
    }
    
    private func startVerification() {
        SelvageSdk.startVerification(
            presenter: self,                  // Optional; if not provided, the currently displayed ViewController will be automatically located
            appId: "your-app-id",           
            apiKey: "your-api-key",         
            providerId: "your-provider-id"
        ) { [weak self] result in
            // The callback is executed on the main thread
            switch result {
            case .success(let verificationResult):
                // Verification successful
                print("Verification Successful")
                print("Session ID: \(verificationResult.sessionId)")
                print("Proofs JSON: \(verificationResult.proofsJson)")
                
                // Send proofsJson to the backend for verification
                self?.sendProofsToBackend(verificationResult.proofsJson)
                
            case .failure(let error):
                // Verification failed or canceled
                print("Verification Failed: \(error.localizedDescription)")
                self?.handleVerificationError(error)
            }
        }
    }
    
    private func sendProofsToBackend(_ proofsJson: String) {
        // Implement your backend verification logic
    }
    
    private func handleVerificationError(_ error: Error) {
    }
}

API Reference

SelvageSdk

The main entry class of the SDK, providing static methods.

Method: startVerificationWithAuth

Parameters:

Name	Type	Description
presenter	UIViewController?	The view controller used to present the verification interface. If nil, the SDK automatically locates the currently displayed view controller.
appId	String	Application ID issued by zkTLS.
apiKey	String	API key associated with your application.
providerId	String	Provider identifier for the verification flow.
callback	Callback	Callback interface used to receive verification results.

Return Value: None.

VerificationResult

Result object delivered via the verification success callback when the verification flow completes successfully.

Properties:

Property	Type	Description
sessionId	String	Unique identifier of the verification session.
proofsJson	String	Proof payload in JSON format. This value should be submitted to your backend for verification.

Example: Handling a successful verification result

case .success(let result):
    print("Session ID: \(result.sessionId)")
    print("Proofs JSON: \(result.proofsJson)")

    // Parse proofs JSON if needed
    if let data = result.proofsJson.data(using: .utf8),
       let json = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]] {
        print("Parsed proofs array: \(json)")
    }

VerificationError

Error type delivered via the verification failure callback when the verification flow fails. This error object describes the reason why the verification did not complete successfully.

---

Error Cases:

• invalidArguments(message) Indicates that one or more required arguments are missing or invalid.

• sdkBusy Indicates that the SDK is currently processing another verification request.

• verificationFailed(message, _, type) Indicates that the verification process completed but did not meet the required verification criteria.

• flutterChannelError(code, message, _) Indicates an internal error occurred while communicating with the Flutter platform channel.

---

Example: Handling a verification failure

case .failure(let error):
    if let sdkError = error as? SelvageSdk.VerificationError {
        switch sdkError {

        case .invalidArguments(let message):
            // Handle invalid or missing arguments

        case .sdkBusy:
            // Handle SDK busy state

        case .verificationFailed(let message, _, let type):
            // Handle verification failure

        case .flutterChannelError(let code, let message, _):
            // Handle Flutter channel communication error

        default:
            // Handle other errors
        }
    }

---

FAQs

This section collects common questions and their solutions that developers may encounter while using the SDK.

How to handle network disconnection?

The SDK will throw a zkTlsException upon network disconnection. Developers should catch this exception at the application layer and prompt the user to check their network connection or retry later.

Why did my data collection request fail?

Please check the following: Is the API Key correct? Is the zkTLS backend service address reachable? Is the Provider Schema valid? Is the target URL accessible? Detailed error messages can be obtained by enabling SDK logging.

Does the SDK support data collection from all websites?

The zkTLS protocol theoretically supports all TLS-based HTTPS websites. However, the specific data extraction capability depends on the definition of the Provider Schema and the website structure. For complex websites or those with dynamic content, customized Provider Schemas may be required. It is recommended to thoroughly test target websites before integration.