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

Swift Package Manager
Manual

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

Implementation
SwiftUI Example

The revolutionary V4 SDK featuring Hawcx Smart Connect provides intelligent one-click authentication that automatically handles everything:What Smart Connect Does Automatically:

Intelligent User Recognition: Automatically detects if user is new or existing
Contextual Device Awareness: Knows if device is registered or new
Seamless Flow Management: Guides new users through verification, gives existing users instant access
Unified Experience: Single entry point - no more “Sign Up” vs “Sign In” confusion
Secure OTP Delivery: Sends verification codes only when needed
Advanced Cryptography: Manages all security operations transparently
Secure Token Storage: Stores credentials safely in iOS Keychain
Complete Authentication Intelligence: Handles the entire flow behind one smart button

SDK Methods:

authenticateV4(userid: String, callback: AuthV4Callback) - Initiates Smart Connect flow
submitOtpV4(otp: String) - Submits OTP for verification when needed

SDK Callbacks (AuthV4Callback protocol):

onOtpRequired() - Called when new user/device verification is needed
onAuthSuccess(accessToken: String?, refreshToken: String?, isLoginFlow: Bool) - Called on successful authentication
onError(errorCode: AuthV4ErrorCode, errorMessage: String) - Called when errors occur

Web Login Approval

Implementation
SwiftUI Example

Web login enables cross-platform authentication where users can log into your web application using their mobile device with Smart Connect intelligence.Use Case:

Your application has both web and mobile versions using Hawcx Smart Connect SDK
User visits your web app and initiates login
Web app displays a QR code (generated using Hawcx Web SDK with Smart Connect)
User scans QR code with mobile app
Mobile app shows login session details (browser, location, IP)
User approves the login from mobile
Web app automatically logs the user in with Smart Connect

What the SDK Does Automatically:

Validates PIN with backend
Retrieves and stores session details (browser, location, IP)
Manages web token for approval
Sends approval to complete web login

SDK Methods:

webLogin(pin: String, callback: WebLoginCallback) - Validates PIN from QR code
webApprove(token: String, callback: WebLoginCallback) - Approves web login session

SDK Callbacks (WebLoginCallback protocol):

onSuccess() - Called when operation succeeds
showError(webLoginErrorCode: WebLoginErrorCode, errorMessage: String) - Called on error

SDK Storage:

Saves web_token to UserDefaults after successful PIN validation
Saves sessionDetails with browser/location info to UserDefaults

Biometric Authentication

Implementation
SwiftUI Example

The SDK works seamlessly with iOS biometric authentication and Smart Connect. You implement Face ID/Touch ID verification, then call the SDK’s Smart Connect authentication method:What You Implement:

Face ID/Touch ID prompt and verification
Biometric availability checks
Biometric preference storage

What the SDK Provides:

getLastLoggedInUser() to retrieve the last authenticated user
Smart Connect authenticateV4() for intelligent passwordless login after biometric success
Automatic handling of known device login (no OTP required)

Your Implementation:

Check biometric availability using LAContext
Perform biometric authentication
On success, call SDK’s Smart Connect authenticateV4() method

Device Session Management

Implementation
SwiftUI Example

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

Implementation
SwiftUI Example

The SDK provides detailed error codes through the callback. Here’s how to handle them:SDK Provides:

AuthV4ErrorCode enum with specific error cases
Human-readable error messages
Error details in callback

You Implement:

Error UI (alerts, inline messages)
Retry logic
Navigation based on error type

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

AuthV4ErrorCode
WebLoginErrorCode

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

​clearSessionTokens(forUser: String)

​clearUserKeychainData(forUser: String) ⚠️

​getLastLoggedInUser() -> String

​clearLastLoggedInUser()

​Understanding the Difference

​Troubleshooting

​Error Codes

​Support

Community

Contact Support

Overview

Architecture

Quick Start

Core Features

`clearSessionTokens(forUser: String)`

`clearUserKeychainData(forUser: String)` ⚠️

`getLastLoggedInUser() -> String`

`clearLastLoggedInUser()`

Understanding the Difference

Troubleshooting

Error Codes

Support