Usage (Kotlin)

Overview

The Vouch Android SDK provides a UI flow for initiating and managing verification within your app. It uses the Activity Result APIs, so you can launch the flow from a ComponentActivity or Fragment and handle the result in a single callback.

Initialization

Create a single VouchSdk instance in your Activity or Fragment and keep it alive for the lifetime of that component.

Recommended initialization pattern:

import androidx.activity.ComponentActivity
import com.vlayer.vouch.sdk.VouchSdk

class MainActivity : ComponentActivity() {
    private val vouchSdk = VouchSdk(
        activityResultCaller = this,
        customerId = "YOUR_CUSTOMER_ID",
        apiKey = "YOUR_API_KEY"
    )
}

Requesting a Verification

Call vouchSdk.initialize(context) once before the first prove() call. Initialization fetches customer appearance so the SDK opening screen renders with your brand.

The VouchSdk constructor also accepts an optional languageCode parameter that overrides the device language for SDK UI translations:

private val vouchSdk = VouchSdk(
    activityResultCaller = this,
    customerId = "YOUR_CUSTOMER_ID",
    apiKey = "YOUR_API_KEY",
    languageCode = "pl-PL"
)

Use a BCP 47-style language tag with a lowercase primary language subtag, for example en, pl, en-US, or pl-PL. The SDK uses the primary language subtag for translation lookup. Currently, pl resolves to Polish and unsupported languages fall back to English. If languageCode is omitted or null, the SDK uses the device language.

To start a verification flow, build a ProveConfig and call vouchSdk.prove. The SDK will launch its UI and return a NotarizationRequestSdkResult when finished.

Basic usage example:

import com.vlayer.vouch.sdk.InitializeSdkResult
import com.vlayer.vouch.sdk.NotarizationRequestSdkResult
import com.vlayer.vouch.sdk.ProveConfig
import com.vlayer.vouch.sdk.VouchSdk
import kotlinx.coroutines.launch

class MainActivity : ComponentActivity() {
    private val vouchSdk = VouchSdk(
        activityResultCaller = this,
        customerId = "YOUR_CUSTOMER_ID",
        apiKey = "YOUR_API_KEY",
        languageCode = "pl-PL"
    )

    private fun startProving() {
        val inputs = mapOf<String, String>(
            "inputParamName" to "inputParamValue"
        )
        val proveConfig = ProveConfig(
            datasourceId = "DATA_SOURCE_ID",
            inputs = inputs,
            webhookUrl = "WEBHOOK_URL",
            metadata = "optional-metadata"
        )

        lifecycleScope.launch {
            when (val init = vouchSdk.initialize(this@MainActivity)) {
                is InitializeSdkResult.Success ->
                    vouchSdk.prove(
                        context = this@MainActivity,
                        proveConfig = proveConfig,
                        callback = ::handleNotarizationResult
                    )

                is InitializeSdkResult.Failure -> {
                    // Handle init failure, e.g. show init.message
                }
            }
        }
    }

    private fun handleNotarizationResult(result: NotarizationRequestSdkResult) {
        when (result) {
            is NotarizationRequestSdkResult.Success -> {
                val requestId = result.requestId
                // Handle success
            }
            is NotarizationRequestSdkResult.Failure -> {
                val requestId = result.requestId
                val message = result.message
                // Handle failure
            }
            is NotarizationRequestSdkResult.Canceled -> {
                val requestId = result.requestId
                // Handle cancellation
            }
        }
    }
}

Parameters

The VouchSdk constructor accepts:

• activityResultCaller: the ComponentActivity or Fragment that hosts the SDK. The SDK uses Android's Activity Result API to launch its verification UI and return the result back to your app.
• customerId: your customer ID.
• apiKey: your API key for server-side proof request creation. The SDK calls POST /proof-request with bearer auth before fetching the config.
• languageCode (optional): BCP 47-style language tag used to override the device language for SDK UI translations, such as en, pl, en-US, or pl-PL. Use a lowercase primary language subtag. The SDK uses the primary language subtag for translation lookup. Currently, pl resolves to Polish and unsupported languages fall back to English. Pass null or omit this parameter to use the device language.

The ProveConfig requires your datasourceId and webhookUrl. It also accepts:

• metadata (optional): custom metadata string (1–256 characters) attached to the proof request. It is also returned in the webhook payload.

For detailed documentation on datasourceId, webhookUrl, and inputs, see the Vouch URL Parameters section.

Note: In the Android SDK, inputs is passed as a Map<String, String> and is serialized internally by the SDK.

Result Handling

The callback receives a NotarizationRequestSdkResult:

• Success: verification completed; contains requestId
• Failure: verification failed; contains requestId (nullable) and message (nullable)
• Canceled: user canceled; contains requestId (nullable)