@passgage/sdk-react-native

Complete Passgage Access SDK for React Native with authentication, QR/NFC scanning, check-in, and remote work features.

Installation

npm install @passgage/sdk-react-native
# or
yarn add @passgage/sdk-react-native

Peer Dependencies

You also need to install these peer dependencies:

npm install react-native-vision-camera react-native-nfc-manager @react-native-community/geolocation react-native-keychain

Follow the installation instructions for each native library:

Usage

Provider Setup

Wrap your app with PassgageAccessProvider:

import { PassgageAccessProvider } from '@passgage/sdk-react-native';

function App() {
  return (
    <PassgageAccessProvider
      baseURL="https://your-api.passgage.com"
      onUnauthorized={() => {
        // Handle session expiration
        console.log('Session expired');
      }}
    >
      <YourApp />
    </PassgageAccessProvider>
  );
}

Authentication

import { usePassgageAuth } from '@passgage/sdk-react-native';

function LoginScreen() {
  const { login, logout, user, isLoading, isAuthenticated } = usePassgageAuth({
    onLoginSuccess: (user) => {
      console.log('Logged in:', user?.fullName);
    },
    onLoginError: (error) => {
      console.error('Login failed:', error);
    },
  });

  const handleLogin = async () => {
    await login({
      login: 'user@example.com',
      password: 'password123',
    });
  };

  return (
    <View>
      {isAuthenticated ? (
        <Text>Welcome, {user?.fullName}!</Text>
      ) : (
        <Button title="Login" onPress={handleLogin} disabled={isLoading} />
      )}
    </View>
  );
}

QR Scanner

import { usePassgageQRScanner } from '@passgage/sdk-react-native';

function QRScanScreen() {
  const { scan, isLoading, error } = usePassgageQRScanner({
    onSuccess: (entrance) => {
      console.log('QR scan successful:', entrance);
    },
    onError: (error) => {
      console.error('QR scan failed:', error);
    },
  });

  return (
    <View>
      <Camera
        onCodeScanned={(code) => scan(code)}
        isActive={!isLoading}
      />
    </View>
  );
}

NFC Scanner

import { usePassgageNFCScanner } from '@passgage/sdk-react-native';

function NFCScanScreen() {
  const { startScanning, stopScanning, isScanning } = usePassgageNFCScanner({
    onSuccess: (entrance) => {
      console.log('NFC scan successful:', entrance);
    },
    onError: (error) => {
      console.error('NFC scan failed:', error);
    },
  });

  useEffect(() => {
    startScanning();
    return () => stopScanning();
  }, []);

  return (
    <View>
      <Text>{isScanning ? 'Scanning...' : 'Tap to scan'}</Text>
    </View>
  );
}

Check-In

import { usePassgageCheckIn, usePassgageAuth } from '@passgage/sdk-react-native';

function CheckInScreen() {
  const { user } = usePassgageAuth();
  const { getNearbyBranches, checkInEntry, checkInExit, isLoading } = usePassgageCheckIn();
  const [branches, setBranches] = useState([]);

  useEffect(() => {
    const loadBranches = async () => {
      const result = await getNearbyBranches({ radius: 5000 });
      if (result.success) {
        setBranches(result.data);
      }
    };
    loadBranches();
  }, []);

  const handleCheckIn = async (branchId: string) => {
    const result = await checkInEntry({
      branchId,
      userId: user.id,
    });

    if (result.success) {
      console.log('Checked in successfully');
    }
  };

  return (
    <View>
      {branches.map((branch) => (
        <TouchableOpacity key={branch.id} onPress={() => handleCheckIn(branch.id)}>
          <Text>{branch.title}</Text>
        </TouchableOpacity>
      ))}
    </View>
  );
}

Remote Work

import { usePassgageRemoteWork, usePassgageAuth } from '@passgage/sdk-react-native';

function RemoteWorkScreen() {
  const { user } = usePassgageAuth();
  const { logEntry, logExit, isLoading } = usePassgageRemoteWork();

  const handleStartWork = async () => {
    const result = await logEntry({
      userId: user.id,
      description: 'Working from home',
    });

    if (result.success) {
      console.log('Work entry logged');
    }
  };

  const handleEndWork = async () => {
    const result = await logExit({
      userId: user.id,
      description: 'Finished work',
    });

    if (result.success) {
      console.log('Work exit logged');
    }
  };

  return (
    <View>
      <Button title="Start Work" onPress={handleStartWork} disabled={isLoading} />
      <Button title="End Work" onPress={handleEndWork} disabled={isLoading} />
    </View>
  );
}

API

Hooks

All hooks use the usePassgage* prefix to avoid naming conflicts:

usePassgageAuth() - Authentication and user management
usePassgageQRScanner() - QR code scanning with validation
usePassgageNFCScanner() - NFC card scanning with validation
usePassgageCheckIn() - GPS-based check-in with nearby branches
usePassgageRemoteWork() - Remote work entry/exit logging
useLocation() - Location tracking and permissions
usePassgageAccess() - Access SDK context and services

Components

<PassgageAccessProvider> - SDK configuration provider

Services

Low-level services are also available through usePassgageAccess():

authService - Authentication operations
qrAccessService - QR code validation
nfcAccessService - NFC card validation
checkInService - Check-in operations
remoteWorkService - Remote work logging
locationService - Location management
deviceAccessService - Device operations

Security Features

JWT Authentication: Secure token-based authentication
Automatic Token Refresh: Tokens are automatically refreshed when expired
Secure Storage: Tokens stored securely using platform-specific secure storage
TLS 1.2+: All network communications encrypted
Location Verification: Automatic location validation with range checking
Anti-Passback: Support for anti-passback rules

Token Flow

The SDK automatically handles authentication tokens:

User logs in → JWT tokens stored securely
API client automatically adds Authorization: Bearer {token} to all requests
Tokens are automatically refreshed when they expire
On logout, all tokens are cleared

You don't need to manually manage tokens! Just use the hooks and the SDK handles everything.

Example Application

A complete example React Native app demonstrating all SDK features:

👉 Passgage SDK Example App

TypeScript Support

The SDK is written in TypeScript and includes full type definitions for all APIs, hooks, and models.

License

Support

For support, contact devops@passgage.com