Hawcx React Native SDK with Smart Connect

Bring Hawcx Smart Connect to React Native using our production iOS and Android SDKs.

Overview

The Hawcx React Native SDK delivers the same Smart Connect passwordless experience that powers our native apps. The package wraps the production Hawcx iOS and Android frameworks so you can orchestrate registration and login through a single JavaScript API.

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

Enterprise-Grade Security

Production iOS cryptography and secure storage surfaced to React Native

Client-Side Simplicity

Hooks and helpers remove the need to juggle callbacks manually

Unified Native SDKs

The React bridge delegates to the same production Swift and Kotlin SDKs that power our mobile apps

Architecture

The TypeScript surface forwards every security-critical operation to the same HawcxSDK code that runs inside our production iOS and Android apps.

Quick Start

1. Install the SDK

   React Native (iOS)

   1. Add the package to your React Native project (pin to the latest published version):

   npm install @hawcx/react-native-sdk@1.0.4
   

   2. Declare the pod dependency in your ios/Podfile so native builds stay in sync with the npm package:

   pod 'HawcxReactNative', '1.0.4'   # or use '~> 1.0' for minor updates
   

   3. Install iOS pods so the bundled HawcxFramework.xcframework links correctly:

   cd ios && pod install
   

   4. Open the ios/*.xcworkspace in Xcode and build once so the native module is registered.
   5. Keep your project API key and tenant base URL handy—you’ll pass both to initialize() during app bootstrap. The base URL is the host we provisioned for your environment (example: https://hawcx-api.hawcx.com). Do not append /hc_auth; the native SDK adds all endpoint paths automatically.

   The Podspec included in the package automatically embeds the latest Hawcx framework; no manual framework copying is required. CocoaPods will pick up the right pod when you run pod install.

2. Initialize Hawcx Smart Connect

   React Native (iOS)

   import { useEffect } from 'react';
   import { initialize, addAuthListener } from '@hawcx/react-native-sdk';
   
   export async function bootstrapHawcx() {
     await initialize({
       projectApiKey: 'YOUR_API_KEY',
       baseUrl: 'https://your-tenant.hawcx-api.hawcx.com',
     });
   
     const subscription = addAuthListener((event) => {
       if (event.type === 'auth_error') {
         console.warn('Hawcx error', event.payload);
       }
     });
   
     return () => subscription.remove();
   }
   

   Call bootstrapHawcx() once (e.g., inside your root provider). All subsequent API calls—authenticate, hooks, or helper clients—reuse the same native singleton.

   baseUrl must be the scheme + host that Hawcx provisioned for your tenant (for example https://hawcx-api.hawcx.com).

   Do not pass OAuth client credentials to initialize. Those values belong on your backend only; the mobile SDK should receive authorization codes and forward them for verification.

3. Implement Smart Connect authentication

   Core Features

   The React SDK exposes the same Smart Connect authentication flow as our native apps: a single method (authenticate) handles login vs registration, and OTP collection happens only when the backend requires additional verification. The sections below mirror the native documentation with React-specific guidance.

   Smart Connect Authentication

   Implementation

   The Smart Connect bridge exposes everything you need to start a passwordless authentication flow from JavaScript:

   What Smart Connect Does Automatically

   • Detects whether the identifier belongs to a new or existing user
   • Determines if the current device is trusted or needs OTP verification
   • Handles the entire Ed25519 key exchange and secure storage on the native side
   • Stores access/refresh tokens inside the Secure Enclave/Keychain when the SDK redeems the authorization code on your behalf

   React SDK Methods

   • initialize(config) – configures the shared native instance; requires both the Hawcx projectApiKey and your tenant baseUrl
   • authenticate(userId) – begins Smart Connect for a given identifier
   • submitOtp(code) – forwards the 6-digit OTP when required
   • addAuthListener(listener) / useHawcxAuth() – receive OTP, authorization code, additional verification, success, and error events
   • storeBackendOAuthTokens(userId, { accessToken, refreshToken? }) – persist tokens returned by your backend after it redeems the authorization code
   • hawcxClient.authenticate(userId, options) – promise-based helper that resolves when tokens exist; use onAuthorizationCode to drive backend exchange

   End-to-End Flow

   1. Collect the user’s identifier (email/username).

   2. Call authenticate(userId) from React.

   3. When otp_required fires (new-device or high-risk scenarios), show OTP UI and pass the six-digit code to submitOtp.

   4. Once the OTP (if any) is accepted, the SDK completes the device check and emits an authorization_code event with the short-lived code.

   5. Immediately send { code, email, expires_in } to your backend over HTTPS. Codes expire quickly, so do not wait for additional user input before forwarding them.

   6. Your backend uses the Hawcx OAuth Client with its provisioned credentials (clientId, token endpoint, Hawcx public key, and your private key) to exchange the code for JWTs and verify the signature.

   7. Return { access_token, refresh_token } (or whatever session format you prefer) to the app. Call storeBackendOAuthTokens(userId, tokens) so the native SDK writes them into the Keychain/Keystore before navigating the user into protected areas.

   Smart Connect removes the need to build separate “Sign Up”/“Sign In” flows. A single call handles every branch while the native layer keeps secrets off the JS heap.

   OTP Handling & UI State

   Implementation

   • Listen to otp_required events through useHawcxAuth or addAuthListener
   • Keep OTP UI local to React; the native layer only validates the code
   • Use hawcxClient.authenticate(userId, { onOtpRequired }) when you want a promise you can await (e.g., inside Redux sagas)
   • useHawcxAuth().reset() clears hook state so you can restart the flow without remounting components

   Biometric Authentication

   Implementation

   • Use your preferred biometric library (e.g., react-native-biometrics) to gate access
   • Store the last successful Hawcx identifier in secure storage after each auth_success
   • When biometrics succeed, call hawcxClient.authenticate(lastUser) to resume Smart Connect without prompting for the identifier again
   • If the device was wiped or secrets were cleared, the SDK automatically falls back to OTP verification

   Device Session Management

   Implementation

   The React SDK can fetch device metadata from the DevSession service so you can show users where they are logged in and offer local device cleanup actions.

   • Call hawcxClient.fetchDeviceDetails() to ask the native layer for current device information
   • Subscribe to addSessionListener to get session_success or session_error callbacks
   • Present the device list (browser, OS, timestamps) inside your security settings UI
   • Clearing tokens/device keys still happens natively; expose UI toggles now so you can connect the upcoming JS helpers without redesigning screens

Troubleshooting

Authorization code never completes login

Symptoms: authorization_code events fire but the UI never navigates away from the login screen.

Fixes:

1. Confirm the frontend calls your backend with { code, email, expires_in }.
2. Ensure the backend exchanges the code via @hawcx/oauth-client and returns { access_token, refresh_token }.
3. Call storeBackendOAuthTokens(userId, tokens) and notifyUserAuthenticated() after the backend response so the native SDK can persist tokens and continue push registration.
4. When testing from a device, expose your backend with ngrok and paste the HTTPS URL into the example app.

Smart Connect returns networkError

Symptoms: auth_error events with networkError and the flow stops.

Fixes:

1. Verify the device has connectivity (simulator proxies, VPNs, etc.)
2. Double-check projectApiKey, baseUrl, and any environment overrides passed to initialize
3. Implement exponential backoff when retrying authenticate:

async function retrySmartConnect(userId: string, attempts = 3) {
  for (let attempt = 1; attempt <= attempts; attempt += 1) {
    try {
      await authenticate(userId);
      return;
    } catch (error) {
      if (attempt === attempts) throw error;
      await new Promise((resolve) => setTimeout(resolve, attempt * 2000));
    }
  }
}

OTP verification fails

Symptoms: Users get stuck on the OTP screen or see otpVerificationFailed errors.

Fixes:

1. Limit input to 6 digits client-side (see the example above using replace(/[^0-9]/g, ''))
2. Remind users that codes expire after 5 minutes—show a countdown next to the submit button
3. Enable iOS OTP auto-fill by setting textContentType="oneTimeCode" on your TextInput

Biometrics unavailable

Symptoms: Face ID / Touch ID prompts never appear or fail immediately.

Fixes:

1. Ensure your app requests permission in Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>Authenticate quickly with Face ID</string>

2. Use react-native-biometrics (or similar) to check isSensorAvailable() before prompting
3. Fall back to Smart Connect + OTP whenever biometrics return an error

State machine gets stuck

Symptoms: The hook remains in pending or otp even after navigating away.

Fixes:

1. Call reset() from useHawcxAuth when leaving the screen to clear internal counters
2. Remove lingering listeners created via addAuthListener during useEffect cleanup
3. If you manually call hawcxClient.authenticate, keep a reference to { cancel } so you can abort when the user backs out

Login works locally but backend sessions are missing

Symptoms: auth_success fires in React, but users never obtain a session token from your backend.

Fixes:

1. Ensure your frontend forwards the entire auth_success payload to your backend before navigating away
2. Confirm the backend calls the Hawcx OAuth verification endpoint (tokenEndpoint) with the client credentials we issued
3. Validate that the IDP response (JWTs) is stored/returned from your backend so the app can complete login
4. Audit server logs for HTTP 4xx/5xx responses from the verification endpoint—most issues stem from missing or incorrect client IDs