Hawcx Android SDK with Smart Connect

Overview

Hawcx SDK delivers revolutionary Smart Connect technology - the most intuitive passwordless authentication ever created for Android applications. Smart Connect intelligently handles both sign up and sign in through a single, unified interface, eliminating decision fatigue while maintaining enterprise-grade security.

Smart Connect Technology

One-click intelligent authentication that automatically determines user context

Contextual Intelligence

No more “Sign Up” vs “Sign In” confusion - just one smart entry point

Seamless Cross-Platform

Smart Connect maintains user context across all devices and platforms

Web Login Approval

Allow users to approve web logins from their mobile device

Enterprise-Grade Security

Revolutionary security with consumer-grade simplicity

Architecture

Quick Start

Installation

dependencies {
    implementation 'com.hawcx:hawcx-android-sdk:4.0.0'
}

Initialize SDK

import com.hawcx.internal.HawcxSDK

class MainApplication : Application() {
    companion object {
        lateinit var hawcxSdkInstance: HawcxSDK
            private set
    }

    override fun onCreate() {
        super.onCreate()
        
        // Initialize Hawcx SDK with your project API key
        hawcxSdkInstance = HawcxSDK(
            context = this.applicationContext,
            projectApiKey = "YOUR_API_KEY"
        )
    }
}

Don’t forget to register your Application class in the AndroidManifest.xml:

<application
    android:name=".YourApplication"
    ...>
    <!-- Activities and other components -->
</application>

Implement Smart Connect authentication:

Core Features

Smart Connect Authentication

Web Login Approval

Biometric Authentication

Device Session Management

What the SDK Manages:

JWT tokens (access & refresh) in Android Keystore
Device registration keys in Android Keystore
Last logged-in user identifier
Secure cleanup of credentials

SDK Methods (all are suspend functions):

`suspend fun clearSessionTokens(userid: String): Boolean`

Purpose: Standard logout functionality
What it does:

Removes JWT access and refresh tokens from Keystore
Preserves device registration (Er1r2 and persistent device token)
User can log back in without OTP verification
Device remains trusted

When to use:

Standard “Log Out” button functionality
Switching between accounts on same device
Temporary sign out

Example:

fun logoutCurrentUser() {
    lifecycleScope.launch {
        val userId = getCurrentUserId()
        val success = sdk.clearSessionTokens(userid = userId)
        if (success) {
            // User will use Smart Connect but no OTP needed
            navigateToSmartConnectScreen()
        }
    }
}

`suspend fun clearUserKeychainData(userid: String): Boolean` ⚠️

Purpose: Complete device removal
What it does:

Removes ALL user data from Keystore:
JWT tokens (access & refresh)
Device registration keys (Er1r2)
Persistent device token
All cryptographic material
User will need OTP to use this device again
Device is no longer trusted

When to use:

“Remove this device” functionality
Security breach response
Before selling/giving away device
Complete account removal

⚠️ WARNING: This is destructive! Do NOT use for standard logout.Example:

fun removeDeviceCompletely() {
    lifecycleScope.launch {
        val userId = getCurrentUserId()
        // Confirm with user first!
        showConfirmationDialog("Remove this device?") { confirmed ->
            if (confirmed) {
                lifecycleScope.launch {
                    val success = sdk.clearUserKeychainData(userid = userId)
                    if (success) {
                        // Smart Connect will require OTP next time
                        navigateToSmartConnectScreen()
                    }
                }
            }
        }
    }
}

`suspend fun getLastLoggedInUsername(): String`

Purpose: UI convenience for Smart Connect screen
What it returns:

Email/identifier of last successfully authenticated user
Empty string if no user has logged in

When to use:

Pre-filling email field on Smart Connect screen
Enabling biometric login for returning users
Showing “Welcome back, [email]” messages

Example:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    
    lifecycleScope.launch {
        // Pre-fill email field
        val lastUser = sdk.getLastLoggedInUsername()
        if (lastUser.isNotEmpty()) {
            emailEditText.setText(lastUser)
            
            // Check if biometrics enabled for this user
            if (isBiometricEnabled(lastUser)) {
                showBiometricLoginButton()
            }
        }
    }
}

`suspend fun clearLastLoggedInUser(): Boolean`

Purpose: Clear the UI pre-fill record
What it does:

Only removes the “last user” marker
Does NOT affect authentication state
Does NOT remove any tokens or keys
Next app launch won’t pre-fill email

When to use:

“Switch Account” functionality
Privacy mode where email shouldn’t be shown
App reset (keeping users logged in)

Example:

fun switchToNewAccount() {
    lifecycleScope.launch {
        // Clear pre-fill but keep current user logged in
        sdk.clearLastLoggedInUser()
        
        // Show fresh Smart Connect screen
        presentSmartConnectScreen(preFillEmail = false)
    }
}

Understanding the Difference

Action	Method to Use	User Experience	OTP Required?
Log Out	`clearSessionTokens()`	Must use Smart Connect again	❌ No
Remove Device	`clearUserKeychainData()`	Device registration lost	✅ Yes
Hide Email Pre-fill	`clearLastLoggedInUser()`	No change to auth	N/A
Check Last User	`getLastLoggedInUsername()`	Shows last email	N/A

Error Handling

Troubleshooting

Smart Connect Authentication Fails with Network Error

Symptoms:

NETWORK_ERROR returned in callback
Smart Connect doesn’t proceed

Solutions:

Check internet connectivity
Verify API key is correct
Ensure no firewall/proxy blocking
Add network permission to manifest:

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

Implement retry logic with exponential backoff:

fun retrySmartConnect(attempts: Int = 3) {
    var currentAttempt = 0
    
    fun attempt() {
        sdk.authenticateV4(userid = email, callback = this)
    }
    
    // In error callback
    if (errorCode == AuthV4ErrorCode.NETWORK_ERROR && currentAttempt < attempts) {
        currentAttempt++
        lifecycleScope.launch {
            delay(currentAttempt * 2000L) // Exponential backoff
            attempt()
        }
    }
}

OTP Verification Fails

Symptoms:

OTP_VERIFICATION_FAILED error
User cannot proceed past OTP screen

Solutions:

Ensure OTP is exactly 6 digits
Check if OTP expired (5 minute validity)
Enable auto-fill for better UX:

// In your OTP EditText
otpEditText.setAutofillHints(View.AUTOFILL_HINT_SMS_OTP)

Biometric Authentication Issues

Symptoms:

Biometric prompt doesn’t appear
Authentication fails immediately

Solutions:

Add to AndroidManifest.xml:

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

Check biometric availability:

val biometricManager = BiometricManager.from(context)
when (biometricManager.canAuthenticate(BIOMETRIC_STRONG or DEVICE_CREDENTIAL)) {
    BiometricManager.BIOMETRIC_SUCCESS ->
        Log.d("Biometric", "App can authenticate using biometrics.")
    BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE ->
        Log.e("Biometric", "No biometric features available on this device.")
    BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE ->
        Log.e("Biometric", "Biometric features are currently unavailable.")
    BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED ->
        Log.e("Biometric", "User hasn't enrolled any biometrics.")
}

Handle specific biometric errors:

override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
    when (errorCode) {
        BiometricPrompt.ERROR_USER_CANCELED -> {
            // User cancelled
        }
        BiometricPrompt.ERROR_LOCKOUT -> {
            // Too many attempts
            showMessage("Too many failed attempts. Try again later.")
        }
        BiometricPrompt.ERROR_LOCKOUT_PERMANENT -> {
            // Permanent lockout
            showMessage("Biometric authentication is disabled.")
        }
        else -> {
            showMessage("Biometric error: $errString")
        }
    }
}

Keystore Access Issues

Symptoms:

KEYCHAIN_SAVE_FAILED errors
Login state not persisted

Solutions:

Ensure device has secure lock screen:

val keyguardManager = context.getSystemService(Context.KEYGUARD_SERVICE) as KeyguardManager
if (!keyguardManager.isDeviceSecure) {
    // Prompt user to set up lock screen
}

Handle Keystore exceptions:

try {
    // Keystore operations
} catch (e: UserNotAuthenticatedException) {
    // User needs to unlock device
} catch (e: KeyPermanentlyInvalidatedException) {
    // Keys invalidated, need to re-register
}

Error Codes

Error Code	Description
`FINGERPRINT_ERROR`	Failed to generate device fingerprint
`KEYCHAIN_SAVE_FAILED`	Failed to save data to Android Keystore
`CLIENT_CRYPTO_ERROR`	Cryptographic operation failed on device
`AUTH_INIT_FAILED`	Authentication initialization failed
`OTP_VERIFICATION_FAILED`	Invalid or expired OTP
`DEVICE_VERIFICATION_FAILED`	Device registration verification failed
`CIPHER_VERIFICATION_FAILED`	Login cipher verification failed
`NETWORK_ERROR`	Network connectivity issue or request timeout
`INTERNAL_STATE_ERROR`	SDK internal state corruption
`MISSING_DEVICE_TOKEN_SESSION`	Session token missing during flow
`UNKNOWN_ERROR`	Unexpected error occurred

Get Started

Dashboard

API Documentation

Hawcx Android SDK with Smart Connect

Overview

Smart Connect Technology

Contextual Intelligence

Seamless Cross-Platform

Web Login Approval

Enterprise-Grade Security

Architecture

Quick Start

Core Features

`suspend fun clearSessionTokens(userid: String): Boolean`

`suspend fun clearUserKeychainData(userid: String): Boolean` ⚠️

`suspend fun getLastLoggedInUsername(): String`

`suspend fun clearLastLoggedInUser(): Boolean`

Understanding the Difference

Troubleshooting

Error Codes

Support

Community

Contact Support

Get Started

Dashboard

API Documentation

​Overview

Smart Connect Technology

Contextual Intelligence

Seamless Cross-Platform

Web Login Approval

Enterprise-Grade Security

​Architecture

​Quick Start

​Core Features

​Troubleshooting

​Error Codes

​Support

Community

Contact Support

Overview

Architecture

Quick Start

Core Features

Troubleshooting

Error Codes

Support