Android SDK

Overview

The Vouch Android SDK provides email validation and device fingerprinting for native Android applications. Built with Kotlin, it integrates seamlessly with both Jetpack Compose and traditional Views.

Package: com.github.vouch-platform:vouch-sdk Platform: Android 8.0+ (API 26+) Language: Kotlin 1.9+ Distribution: JitPack (Gradle/Maven)

Installation

JitPack (Recommended)

Add JitPack repository to your root build.gradle.kts or settings.gradle.kts:

build.gradle.kts

repositories {
    maven { url = uri("https://jitpack.io") }
}

Add the dependency:

build.gradle.kts

dependencies {
    implementation("com.github.vouch-platform:vouch-sdk:2.0.0")
}

Permissions

Add internet permission to your AndroidManifest.xml:

AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />

No other permissions required. The SDK only needs internet access to communicate with the Vouch API.

Quick Start

import expert.vouch.sdk.Vouch
import kotlinx.coroutines.launch

// Initialize the SDK
val vouch = Vouch(
    context = applicationContext,
    projectId = "your-project-id",
    apiKey = "your-client-api-key"
)

// Validate an email
lifecycleScope.launch {
    val result = vouch.validate("[email protected]")

    if (result.success && result.valid == true) {
        println("✓ Email is valid")
    } else {
        println("✗ Invalid email: ${result.error}")
    }
}

Jetpack Compose Integration

Basic Form Validation

import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import expert.vouch.sdk.Vouch
import kotlinx.coroutines.launch

@Composable
fun SignUpScreen() {
    val context = LocalContext.current
    val scope = rememberCoroutineScope()

    val vouch = remember {
        Vouch(
            context = context.applicationContext,
            projectId = "your-project-id",
            apiKey = "your-client-api-key"
        )
    }

    var email by remember { mutableStateOf("") }
    var isValidating by remember { mutableStateOf(false) }
    var validationMessage by remember { mutableStateOf<String?>(null) }
    var isValid by remember { mutableStateOf(false) }

    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(16.dp),
        verticalArrangement = Arrangement.spacedBy(16.dp)
    ) {
        OutlinedTextField(
            value = email,
            onValueChange = {
                email = it
                validationMessage = null
            },
            label = { Text("Email Address") },
            modifier = Modifier.fillMaxWidth(),
            enabled = !isValidating,
            singleLine = true
        )

        Button(
            onClick = {
                scope.launch {
                    isValidating = true
                    validationMessage = null

                    val result = vouch.validate(email)

                    isValidating = false

                    if (result.success && result.valid == true) {
                        isValid = true
                        validationMessage = "✓ Valid email"
                        // Proceed with sign-up
                    } else {
                        isValid = false
                        validationMessage = result.error ?: "Email validation failed"
                    }
                }
            },
            enabled = !isValidating && email.isNotEmpty(),
            modifier = Modifier.fillMaxWidth()
        ) {
            Text(if (isValidating) "Validating..." else "Sign Up")
        }

        validationMessage?.let { message ->
            Text(
                text = message,
                color = if (isValid) MaterialTheme.colorScheme.primary else MaterialTheme.colorScheme.error,
                style = MaterialTheme.typography.bodySmall
            )
        }

        if (isValidating) {
            LinearProgressIndicator(modifier = Modifier.fillMaxWidth())
        }
    }
}

Real-Time Validation

import androidx.compose.runtime.*
import kotlinx.coroutines.Job
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch

@Composable
fun RealtimeEmailField() {
    val context = LocalContext.current
    val scope = rememberCoroutineScope()

    val vouch = remember {
        Vouch(
            context = context.applicationContext,
            projectId = "your-project-id",
            apiKey = "your-client-api-key"
        )
    }

    var email by remember { mutableStateOf("") }
    var validationState by remember { mutableStateOf<ValidationState>(ValidationState.Idle) }
    var validationJob by remember { mutableStateOf<Job?>(null) }

    LaunchedEffect(email) {
        validationJob?.cancel()

        if (email.isEmpty()) {
            validationState = ValidationState.Idle
            return@LaunchedEffect
        }

        validationState = ValidationState.Validating

        validationJob = scope.launch {
            delay(500) // Debounce

            val result = vouch.validate(email)

            validationState = if (result.success && result.valid == true) {
                ValidationState.Valid
            } else {
                ValidationState.Invalid(result.error ?: "Invalid email")
            }
        }
    }

    Row(
        modifier = Modifier.fillMaxWidth(),
        horizontalArrangement = Arrangement.spacedBy(8.dp),
        verticalAlignment = Alignment.CenterVertically
    ) {
        OutlinedTextField(
            value = email,
            onValueChange = { email = it },
            label = { Text("Email") },
            modifier = Modifier.weight(1f),
            singleLine = true,
            isError = validationState is ValidationState.Invalid
        )

        when (validationState) {
            ValidationState.Idle -> {}
            ValidationState.Validating -> CircularProgressIndicator(modifier = Modifier.size(24.dp))
            ValidationState.Valid -> Icon(
                imageVector = Icons.Default.CheckCircle,
                contentDescription = "Valid",
                tint = MaterialTheme.colorScheme.primary
            )
            is ValidationState.Invalid -> Icon(
                imageVector = Icons.Default.Error,
                contentDescription = "Invalid",
                tint = MaterialTheme.colorScheme.error
            )
        }
    }

    if (validationState is ValidationState.Invalid) {
        Text(
            text = (validationState as ValidationState.Invalid).message,
            color = MaterialTheme.colorScheme.error,
            style = MaterialTheme.typography.bodySmall
        )
    }
}

sealed class ValidationState {
    object Idle : ValidationState()
    object Validating : ValidationState()
    object Valid : ValidationState()
    data class Invalid(val message: String) : ValidationState()
}

Traditional View/Activity Integration

Basic Usage

import android.os.Bundle
import android.widget.Button
import android.widget.EditText
import android.widget.TextView
import androidx.appcompat.app.AppCompatActivity
import androidx.core.content.ContextCompat
import androidx.lifecycle.lifecycleScope
import expert.vouch.sdk.Vouch
import kotlinx.coroutines.launch

class SignUpActivity : AppCompatActivity() {
    private val vouch by lazy {
        Vouch(
            context = applicationContext,
            projectId = "your-project-id",
            apiKey = "your-client-api-key"
        )
    }

    private lateinit var emailEditText: EditText
    private lateinit var signUpButton: Button
    private lateinit var resultTextView: TextView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_signup)

        emailEditText = findViewById(R.id.emailEditText)
        signUpButton = findViewById(R.id.signUpButton)
        resultTextView = findViewById(R.id.resultTextView)

        signUpButton.setOnClickListener {
            val email = emailEditText.text.toString()

            if (email.isEmpty()) {
                resultTextView.text = "Please enter an email address"
                resultTextView.setTextColor(ContextCompat.getColor(this, android.R.color.holo_red_dark))
                return@setOnClickListener
            }

            signUpButton.isEnabled = false
            resultTextView.text = "Validating..."
            resultTextView.setTextColor(ContextCompat.getColor(this, android.R.color.darker_gray))

            lifecycleScope.launch {
                val result = vouch.validate(email)

                signUpButton.isEnabled = true

                if (result.success && result.valid == true) {
                    resultTextView.text = "✓ Valid email"
                    resultTextView.setTextColor(ContextCompat.getColor(this@SignUpActivity, android.R.color.holo_green_dark))
                    // Proceed with sign-up
                } else {
                    resultTextView.text = result.error ?: "Invalid email"
                    resultTextView.setTextColor(ContextCompat.getColor(this@SignUpActivity, android.R.color.holo_red_dark))
                }
            }
        }
    }
}

With ViewModel (MVVM Pattern)

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import expert.vouch.sdk.Vouch
import expert.vouch.sdk.models.ValidationResult
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.launch

class SignUpViewModel(private val vouch: Vouch) : ViewModel() {
    private val _validationState = MutableStateFlow<ValidationResult?>(null)
    val validationState: StateFlow<ValidationResult?> = _validationState

    private val _isValidating = MutableStateFlow(false)
    val isValidating: StateFlow<Boolean> = _isValidating

    fun validateEmail(email: String) {
        viewModelScope.launch {
            _isValidating.value = true
            _validationState.value = null

            val result = vouch.validate(email)

            _validationState.value = result
            _isValidating.value = false
        }
    }
}

Configuration

Custom Options

import expert.vouch.sdk.Vouch
import expert.vouch.sdk.models.VouchOptions
import expert.vouch.sdk.models.ApiVersion
import expert.vouch.sdk.models.FingerprintOptions

val options = VouchOptions(
    endpoint = "https://api.vouch.expert",
    version = ApiVersion.Version(1),  // Use /v1/ endpoint
    fingerprintOptions = FingerprintOptions(
        enableFonts = true  // Enable font fingerprinting (slower but more unique)
    )
)

val vouch = Vouch(
    context = applicationContext,
    projectId = "your-project-id",
    apiKey = "your-client-api-key",
    options = options
)

API Version

Control which API version to use:

// Use latest (unversioned) endpoint
val options = VouchOptions(version = ApiVersion.Latest)

// Use specific version
val options = VouchOptions(version = ApiVersion.Version(1))  // Uses /v1/

Core Methods

validate()

Validate an email address with automatic device fingerprinting:

val result = vouch.validate("[email protected]")

// Check validation result
if (result.success && result.valid == true) {
    println("Valid email: ${result.email}")
} else {
    println("Invalid: ${result.error}")
}

Returns: ValidationResult

success

Boolean

Whether the API call was successful

valid

Boolean?

Whether the email is valid (null if success is false)

String?

The normalized email address

error

String?

Error message if validation failed

data

JsonObject?

Complete server response data

statusCode

Int?

HTTP status code

generateFingerprint()

Get the device fingerprint directly without validating an email:

val fingerprint = vouch.generateFingerprint()

println("Device: ${fingerprint.hardware.deviceModel}")
println("Manufacturer: ${fingerprint.hardware.manufacturer}")
println("Screen: ${fingerprint.hardware.screenWidth}x${fingerprint.hardware.screenHeight}")
println("OS: Android ${fingerprint.system.osVersion}")

Returns: Fingerprint with the following signals:

hardware

HardwareSignals

Device hardware information (screen, CPU, memory, model, manufacturer)

fonts

FontSignals

System fonts and SHA-256 hash

system

SystemSignals

Android version, SDK level, language, locale, timezone

storage

StorageSignals

SharedPreferences, KeyStore, FileSystem availability

timestamp

Long

Unix timestamp in milliseconds

version

String

SDK version (e.g., “2.0.0”)

Error Handling

The SDK uses Kotlin suspend functions and returns results rather than throwing exceptions:

val result = vouch.validate(email)

if (!result.success) {
    when {
        result.statusCode == 400 -> {
            // Invalid format
            showError("Please check your email format")
        }
        result.statusCode == 401 -> {
            // Authentication error
            showError("Invalid API key")
        }
        result.statusCode == 0 -> {
            // Network error
            showError("Network connection failed")
        }
        else -> {
            // Other error
            showError(result.error ?: "Validation failed")
        }
    }
}

Common Status Codes

Code	Description	Solution
`200`	Success	Process the result
`400`	Invalid request	Check email format
`401`	Unauthorized	Verify API key and project ID
`429`	Rate limit exceeded	Implement retry with backoff
`0`	Network error	Check internet connection

Privacy & Permissions

Minimal Permissions

The Vouch Android SDK only requires the INTERNET permission:

<uses-permission android:name="android.permission.INTERNET" />

No dangerous permissions required. The SDK does not access location, camera, contacts, or any other sensitive data.

Data Collection

The SDK collects device fingerprint data for fraud prevention. You must disclose this in:

Your app’s privacy policy
Google Play Data Safety form
GDPR/CCPA notices (if applicable)

What data is collected:

Hardware signals: Screen dimensions, CPU cores, memory, device model, manufacturer
Font signals: System fonts and SHA-256 hash
System signals: Android version, SDK level, language, locale, timezone
Storage signals: SharedPreferences, KeyStore, FileSystem availability

No personally identifiable information (PII) is collected. All data is technical device and system information.

ProGuard/R8

The SDK is fully compatible with ProGuard and R8. Obfuscation rules are included automatically in the library. No additional configuration is required.

Performance

Fingerprint Generation: ~100-500ms (first time)
Email Validation: Instant local validation + network request time
Font Collection: ~200-1000ms (can be disabled)

The SDK starts fingerprint generation immediately when initialized, so the first validate() call can reuse the cached fingerprint.

Best Practices

1. Initialize with Application Context

Always use applicationContext to avoid memory leaks:

val vouch = Vouch(
    context = applicationContext,  // ✓ Good
    // context = this,  // ✗ Bad (Activity context)
    projectId = "...",
    apiKey = "..."
)

2. Use Dependency Injection

Inject the Vouch instance using Hilt or Koin:

// Hilt example
@Module
@InstallIn(SingletonComponent::class)
object VouchModule {
    @Provides
    @Singleton
    fun provideVouch(@ApplicationContext context: Context): Vouch {
        return Vouch(
            context = context,
            projectId = BuildConfig.VOUCH_PROJECT_ID,
            apiKey = BuildConfig.VOUCH_API_KEY
        )
    }
}

3. Handle Errors Gracefully

Don’t block users due to validation failures:

val result = vouch.validate(email)

if (result.success && result.valid == true) {
    // Proceed
} else {
    // Show user-friendly error but allow retry
    showError(result.error ?: "Please check your email")
}

4. Use StateFlow for UI Updates

Combine with StateFlow for reactive UI updates:

class EmailViewModel(private val vouch: Vouch) : ViewModel() {
    private val _state = MutableStateFlow(EmailState())
    val state = _state.asStateFlow()

    fun validate(email: String) {
        viewModelScope.launch {
            _state.update { it.copy(isLoading = true) }

            val result = vouch.validate(email)

            _state.update { it.copy(
                isLoading = false,
                isValid = result.success && result.valid == true,
                error = if (!result.success || result.valid != true) result.error else null
            )}
        }
    }
}

API Reference

Vouch

Main SDK class for email validation and fingerprinting.

class Vouch(
    context: Context,
    projectId: String,
    apiKey: String,
    options: VouchOptions = VouchOptions()
) {
    suspend fun validate(email: String): ValidationResult
    suspend fun generateFingerprint(): Fingerprint
}

VouchOptions

SDK configuration options.

data class VouchOptions(
    val endpoint: String = "https://api.vouch.expert",
    val version: ApiVersion = ApiVersion.Latest,
    val fingerprintOptions: FingerprintOptions = FingerprintOptions()
)

ApiVersion

API version specification.

sealed class ApiVersion {
    object Latest : ApiVersion()  // Unversioned endpoint
    data class Version(val number: Int) : ApiVersion()  // Versioned endpoint
}

FingerprintOptions

Fingerprint collection configuration.

data class FingerprintOptions(
    val enableFonts: Boolean = true  // Default: true (~200-1000ms)
)

Support

For issues and questions:

GitHub: github.com/vouch-platform/vouch-sdk
Email: [email protected]
Documentation: docs.vouch.expert

JavaScript/TypeScript

Frameworks

Mobile

Overview

Installation

JitPack (Recommended)

Permissions

Quick Start

Jetpack Compose Integration

Basic Form Validation

Real-Time Validation

Traditional View/Activity Integration

Basic Usage

With ViewModel (MVVM Pattern)

Configuration

Custom Options

API Version

Core Methods

validate()

generateFingerprint()

Error Handling

Common Status Codes

Privacy & Permissions

Minimal Permissions

Data Collection

ProGuard/R8

Performance

Best Practices

1. Initialize with Application Context

2. Use Dependency Injection

3. Handle Errors Gracefully

4. Use StateFlow for UI Updates

API Reference

Vouch

VouchOptions

ApiVersion

FingerprintOptions

Support

JavaScript/TypeScript

Frameworks

Mobile

​Overview

​Installation

​JitPack (Recommended)

​Permissions

​Quick Start

​Jetpack Compose Integration

​Basic Form Validation

​Real-Time Validation

​Traditional View/Activity Integration

​Basic Usage

​With ViewModel (MVVM Pattern)

​Configuration

​Custom Options

​API Version

​Core Methods

​validate()

​generateFingerprint()

​Error Handling

​Common Status Codes

​Privacy & Permissions

​Minimal Permissions

​Data Collection

​ProGuard/R8

​Performance

​Best Practices

​1. Initialize with Application Context

​2. Use Dependency Injection

​3. Handle Errors Gracefully

​4. Use StateFlow for UI Updates

​API Reference

​Vouch

​VouchOptions

​ApiVersion

​FingerprintOptions

​Support

Overview

Installation

JitPack (Recommended)

Permissions

Quick Start

Jetpack Compose Integration

Basic Form Validation

Real-Time Validation

Traditional View/Activity Integration

Basic Usage

With ViewModel (MVVM Pattern)

Configuration

Custom Options

API Version

Core Methods

validate()

generateFingerprint()

Error Handling

Common Status Codes

Privacy & Permissions

Minimal Permissions

Data Collection

ProGuard/R8

Performance

Best Practices

1. Initialize with Application Context

2. Use Dependency Injection

3. Handle Errors Gracefully

4. Use StateFlow for UI Updates

API Reference

Vouch

VouchOptions

ApiVersion

FingerprintOptions

Support