Skip to main content

​
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 framework so you can orchestrate registration and login through a single JavaScript API while the Android implementation is being finalized.

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

Future Android Support

React integration is ready for iOS today with Android arriving shortly

​
Architecture

The TypeScript surface forwards every security-critical operation to the same HawcxSDK code that runs inside our native iOS app. Android bindings will share this exact architecture when released, so everything documented below applies cross-platform.

​
Quick Start

1

Install the SDK

  • React Native (iOS)
  • React Native (Android – coming soon)
  1. Add the package to your React Native project (pin to the latest published version):
npm install @hawcx/[email protected]
  1. Declare the pod dependency in your ios/Podfile so native builds stay in sync with the npm package:
pod 'HawcxReactNative', '1.0.1'   # or use '~> 1.0' for minor updates
  1. Install iOS pods so the bundled HawcxFramework.xcframework links correctly:
cd ios && pod install
  1. Open the ios/*.xcworkspace in Xcode and build once so the native module is registered.
  2. Keep your project API key handy—you’ll pass it to initialize() during app bootstrap.
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)
  • React Native (Android – coming soon)
import { useEffect } from 'react';
import { initialize, addAuthListener } from '@hawcx/react-native-sdk';

export async function bootstrapHawcx() {
  await initialize({
    projectApiKey: 'YOUR_API_KEY',
    // Optional overrides
    oauthConfig: {
      clientId: 'YOUR_CLIENT_ID',
      tokenEndpoint: 'https://auth.your-domain.com/token',
      publicKeyPem: '-----BEGIN PUBLIC KEY-----...'
    },
  });

  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.
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.
  • Implementation
  • React Native (iOS)
  • Backend Verification (Node.js)
  • React Native (Android – coming soon)
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 (not JS)
React SDK Methods
  • initialize(config) – configures the shared native instance
  • authenticate(userId) – begins Smart Connect for a given identifier
  • submitOtp(code) – forwards the 6-digit OTP when required
  • addAuthListener(listener) / useHawcxAuth() – receive OTP, success, and error events
  • hawcxClient.authenticate(userId, options) – promise-based helper that resolves with tokens when the flow completes
End-to-End Flow
  1. Collect the user’s identifier (email/username).
  2. Call authenticate(userId) from React.
  3. When otp_required fires, show OTP UI and pass the six-digit code to submitOtp.
  4. Wait for auth_success. The payload includes the Hawcx-issued authorization code (and metadata) that must be validated server-side.
  5. Send the entire auth_success payload plus the user identifier to your backend over HTTPS.
  6. Your backend calls the Hawcx OAuth verification endpoint (provided via tokenEndpoint) with its clientId and private credentials to exchange the code with our IDP. The IDP responds with JWTs that represent a verified Hawcx session.
  7. Once the backend confirms the exchange succeeded, issue your own application session (cookies/tokens), notify the React app, and allow 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.
  • Implementation
  • React Native (iOS)
  • React Native (Android – coming soon)
  • 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
  • Implementation
  • React Native (iOS)
  • React Native (Android – coming soon)
  • 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
  • Implementation
  • React Native (iOS)
  • React Native (Android – coming soon)
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

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 and 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));
    }
  }
}
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
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>
  1. Use react-native-biometrics (or similar) to check isSensorAvailable() before prompting
  2. Fall back to Smart Connect + OTP whenever biometrics return an error
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
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