React Native SDK - Address Verification

A React Native package for SID Address Verification with location tracking capabilities.

Installation

npm install rn-sid-address-verification

Or with Yarn:

yarn add rn-sid-address-verification

Visit our npm page for more details.

Platform Setup

iOS Setup

Navigate to the iOS directory and install pods:

cd ios && pod install

Add the following to your ios/YourApp/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs location access to verify your address</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs continuous location access for address verification</string>
<key>UIBackgroundModes</key>
<array>
    <string>location</string>
    <string>processing</string>
</array>

Android Setup

Add these permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

Ensure your build.gradle has:

minSdkVersion 24

Usage

Import the Package

import {
  startTrackingWithConfig,
  stopTracking,
  fetchConfiguration,
} from 'rn-sid-address-verification';

Fetch Configuration

Retrieve the configuration settings from the server:

const config = await fetchConfiguration('api-key', 'token', 'refresh-token');
console.log('Configuration:', config);
// Returns: { pollingInterval: number, sessionTimeout: number }

Start Tracking

Begin location tracking with the provided configuration:

try {
  const success = await startTrackingWithConfig(
    'your-api-key',
    'user-access-token',
    'user-refresh-token'
  );

  if (success) {
    console.log('Tracking started successfully');
  } else {
    console.log('Failed to start tracking');
  }
} catch (error) {
  console.error('Error starting tracking:', error);
}

Stop Tracking

Stop location tracking when no longer needed:

try {
  await stopTracking();
  console.log('Tracking stopped successfully');
} catch (error) {
  console.error('Error stopping tracking:', error);
}

API Reference

Methods

Method	Description	Parameters	Returns
`fetchConfiguration`	Fetches configuration from the server	`apiKey: string`, `token: string`, `refreshToken: string`	`Promise<{pollingInterval: number, sessionTimeout: number}>`
`startTrackingWithConfig`	Starts location tracking with configuration	`apiKey: string`, `token: string`, `refreshToken: string`	`Promise<boolean>`
`stopTracking`	Stops location tracking	None	`Promise<void>`

Configuration Object

interface Configuration {
  pollingInterval: number;  // Interval between location updates (in milliseconds)
  sessionTimeout: number;   // Session timeout duration (in milliseconds)
}

Complete Example

import React, { useEffect, useState } from 'react';
import { View, Button, Text, Alert } from 'react-native';
import {
  startTrackingWithConfig,
  stopTracking,
  fetchConfiguration,
} from 'rn-sid-address-verification';

const AddressVerification = () => {
  const [isTracking, setIsTracking] = useState(false);
  const [config, setConfig] = useState(null);

  const API_KEY = 'your-api-key';
  const ACCESS_TOKEN = 'user-access-token';
  const REFRESH_TOKEN = 'user-refresh-token';

  useEffect(() => {
    loadConfiguration();

    return () => {
      // Cleanup: stop tracking when component unmounts
      if (isTracking) {
        handleStopTracking();
      }
    };
  }, []);

  const loadConfiguration = async () => {
    try {
      const configuration = await fetchConfiguration(
        API_KEY,
        ACCESS_TOKEN,
        REFRESH_TOKEN
      );
      setConfig(configuration);
      console.log('Configuration loaded:', configuration);
    } catch (error) {
      Alert.alert('Error', 'Failed to load configuration');
      console.error('Configuration error:', error);
    }
  };

  const handleStartTracking = async () => {
    try {
      const success = await startTrackingWithConfig(
        API_KEY,
        ACCESS_TOKEN,
        REFRESH_TOKEN
      );

      if (success) {
        setIsTracking(true);
        Alert.alert('Success', 'Tracking started');
      } else {
        Alert.alert('Error', 'Failed to start tracking');
      }
    } catch (error) {
      Alert.alert('Error', error.message);
      console.error('Tracking error:', error);
    }
  };

  const handleStopTracking = async () => {
    try {
      await stopTracking();
      setIsTracking(false);
      Alert.alert('Success', 'Tracking stopped');
    } catch (error) {
      Alert.alert('Error', error.message);
      console.error('Stop tracking error:', error);
    }
  };

  return (
    <View style={{ padding: 20 }}>
      <Text>Address Verification Status: {isTracking ? 'Active' : 'Inactive'}</Text>

      {config && (
        <Text>
          Polling Interval: {config.pollingInterval}ms
          {'\n'}
          Session Timeout: {config.sessionTimeout}ms
        </Text>
      )}

      <Button
        title={isTracking ? 'Stop Tracking' : 'Start Tracking'}
        onPress={isTracking ? handleStopTracking : handleStartTracking}
      />
    </View>
  );
};

export default AddressVerification;

Permissions

Android

Request permissions at runtime:

import { PermissionsAndroid, Platform } from 'react-native';

const requestLocationPermission = async () => {
  if (Platform.OS === 'android') {
    try {
      const granted = await PermissionsAndroid.requestMultiple([
        PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
        PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION,
        PermissionsAndroid.PERMISSIONS.ACCESS_BACKGROUND_LOCATION,
      ]);

      return (
        granted['android.permission.ACCESS_FINE_LOCATION'] === 'granted' &&
        granted['android.permission.ACCESS_COARSE_LOCATION'] === 'granted'
      );
    } catch (err) {
      console.warn(err);
      return false;
    }
  }
  return true;
};

iOS

Permissions are requested automatically when tracking starts, but you must include the usage descriptions in Info.plist.

Troubleshooting

Common Issues

Issue	Solution
Module not found	Run `npm install` or `yarn install` and rebuild the app
iOS build fails	Run `cd ios && pod install --repo-update`
Location not updating	Verify permissions are granted and GPS is enabled
Background tracking not working	Check background mode configuration in Info.plist

Error Handling

Always wrap SDK calls in try-catch blocks:

try {
  await startTrackingWithConfig(apiKey, token, refreshToken);
} catch (error) {
  if (error.message.includes('permission')) {
    // Handle permission errors
  } else if (error.message.includes('network')) {
    // Handle network errors
  } else {
    // Handle other errors
  }
}

Best Practices

Request Permissions Early: Ask for location permissions during app onboarding
Handle Errors Gracefully: Provide user-friendly error messages
Cleanup Resources: Stop tracking when no longer needed
Test Thoroughly: Test on both iOS and Android devices
Monitor Battery Usage: Be mindful of battery consumption with background tracking

Support

For issues or questions: - Visit our npm package page - Contact [email protected] - Check our GitHub repository

Contributing

We welcome contributions! Please see our contributing guidelines for more information.

License

MIT License - See LICENSE for details.