Hawcx iOS SDK with Smart Connect

Overview

Hawcx SDK delivers revolutionary Smart Connect technology - the most intuitive passwordless authentication ever created for iOS 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: [
    .package(url: "https://github.com/hawcx/hawcx_ios_sdk", .upToNextMajor(from: "4.0.0"))
]

Or add it directly in Xcode:

Select File > Add Packages…
Enter the package URL: https://github.com/hawcx/hawcx_ios_sdk
Select “Up to Next Major Version” with version “4.0.0”
Click “Add Package”

Initialize SDK

import HawcxFramework

// Initialize with your project API key
let hawcxSDK = HawcxSDK(projectApiKey: "YOUR_API_KEY")

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 iOS Keychain
Device registration keys in iOS Keychain
Last logged-in user identifier
Secure cleanup of credentials

SDK Methods:

`clearSessionTokens(forUser: String)`

Purpose: Standard logout functionality
What it does:

Removes JWT access and refresh tokens from Keychain
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:

func logoutCurrentUser() {
    let userId = getCurrentUserId()
    sdk.clearSessionTokens(forUser: userId)
    // User will use Smart Connect but no OTP needed
    navigateToLoginScreen()
}

`clearUserKeychainData(forUser: String)` ⚠️

Purpose: Complete device removal
What it does:

Removes ALL user data from Keychain:
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:

func removeDeviceCompletely() {
    let userId = getCurrentUserId()
    // Confirm with user first!
    showConfirmationDialog("Remove this device?") { confirmed in
        if confirmed {
            sdk.clearUserKeychainData(forUser: userId)
            // Smart Connect will require OTP next time
            navigateToLoginScreen()
        }
    }
}

`getLastLoggedInUser() -> 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 func viewDidLoad() {
    super.viewDidLoad()
    
    // Pre-fill email field
    let lastUser = sdk.getLastLoggedInUser()
    if !lastUser.isEmpty {
        emailTextField.text = lastUser
        
        // Check if biometrics enabled for this user
        if isBiometricEnabled(for: lastUser) {
            showBiometricLoginButton()
        }
    }
}

`clearLastLoggedInUser()`

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:

func switchToNewAccount() {
    // 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	`getLastLoggedInUser()`	Shows last email	N/A

Error Handling

Troubleshooting

Smart Connect Authentication Fails with Network Error

Symptoms:

networkError returned in callback
Smart Connect doesn’t proceed

Solutions:

Check internet connectivity
Verify API key is correct
Ensure no firewall/proxy blocking
Implement retry logic with exponential backoff

func retrySmartConnect(attempts: Int = 3) {
    var currentAttempt = 0
    
    func attempt() {
        sdk.authenticateV4(userid: email, callback: self)
    }
    
    // In error callback
    if errorCode == .networkError && currentAttempt < attempts {
        currentAttempt += 1
        DispatchQueue.main.asyncAfter(deadline: .now() + Double(currentAttempt * 2)) {
            attempt()
        }
    }
}

OTP Verification Fails

Symptoms:

otpVerificationFailed 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:

otpTextField.textContentType = .oneTimeCode

Biometric Authentication Issues

Symptoms:

Biometric prompt doesn’t appear
Authentication fails immediately

Solutions:

Add to Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>Authenticate with Face ID for secure access</string>

Check biometric availability:

let context = LAContext()
var error: NSError?

if !context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error) {
    print("Biometrics not available: \(error?.localizedDescription ?? "Unknown")")
}

Handle specific biometric errors:

if let error = error as? LAError {
    switch error.code {
    case .biometryNotEnrolled:
        print("User hasn't set up biometrics")
    case .biometryLockout:
        print("Too many failed attempts")
    case .biometryNotAvailable:
        print("Device doesn't support biometrics")
    default:
        print("Other error: \(error)")
    }
}

Keychain Access Issues

Symptoms:

keychainSaveFailed errors
Login state not persisted

Solutions:

Ensure app has keychain entitlement
Check if device is locked during keychain access
Test keychain availability:

let testQuery: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrAccount as String: "test",
    kSecValueData as String: "test".data(using: .utf8)!
]

let status = SecItemAdd(testQuery as CFDictionary, nil)
if status == errSecInteractionNotAllowed {
    print("Device is locked - keychain not accessible")
}

// Clean up
SecItemDelete(testQuery as CFDictionary)

Error Codes

Error Code	Description
`networkError`	Network connectivity issue or request timeout
`unknownError`	Unexpected error occurred
`invalidInput`	Invalid email or userid format
`keychainSaveFailed`	Failed to save data to iOS Keychain
`clientCryptoError`	Cryptographic operation failed on device
`fingerprintError`	Failed to generate device fingerprint
`authInitFailed`	Authentication initialization failed
`otpVerificationFailed`	Invalid or expired OTP
`deviceVerificationFailed`	Device registration verification failed
`cipherVerificationFailed`	Login cipher verification failed
`internalStateError`	SDK internal state corruption
`missingDeviceTokenSession`	Session token missing during flow
`missingEr1r2ForRegistration`	Cryptographic keys missing
`missingCryptoForLogin`	Device keys not found for login
`missingPersistentDeviceToken`	Device token not found

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

`clearSessionTokens(forUser: String)`

`clearUserKeychainData(forUser: String)` ⚠️

`getLastLoggedInUser() -> String`

`clearLastLoggedInUser()`

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