React Native SDK Usage & Integration

Learn how to initialize the DoorstepAI SDK and integrate delivery tracking into your React Native application.

SDK Initialization

Basic Setup with RootDoorstepAI Component

The easiest way to initialize the SDK is using the RootDoorstepAI component, which handles initialization and permission requests automatically:

App.js

import React from 'react';
import { View, StyleSheet } from 'react-native';
import { DoorstepAI, RootDoorstepAI } from '@doorstepai/dropoff-sdk';

export default function App() {
  return (
    <View style={styles.container}>
      <RootDoorstepAI
        apiKey="your_api_key_here"
        notificationTitle="Tracking..."
        notificationText="Tracking your delivery"
      />
      {/* Your app content */}
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

Core Functionality

Delivery IDs

Delivery IDs are designed to be unique identifiers for each delivery session. Use meaningful, unique identifiers that help you track and manage your deliveries effectively.

Starting Delivery Tracking

The SDK provides multiple methods to start delivery tracking based on different address formats:

1. Start by Place ID

import { DoorstepAI } from '@doorstepai/dropoff-sdk';

const startDeliveryByPlaceID = async () => {
  try {
    const result = await DoorstepAI.startDeliveryByPlaceID(
      'some_place_id',
      'delivery_12345'
    );
    console.log('✅ Delivery started successfully:', result);
    // Handle successful start
  } catch (error) {
    console.error('❌ Failed to start delivery:', error);
    // Handle error
  }
};

2. Start by Plus Code

const startDeliveryByPlusCode = async () => {
  try {
    const result = await DoorstepAI.startDeliveryByPlusCode(
      'some_plus_code',
      'delivery_12345'
    );
    console.log('✅ Delivery started with Plus Code:', result);
  } catch (error) {
    console.error('❌ Plus Code delivery failed:', error);
  }
};

3. Start by Address Components

const startDeliveryByAddress = async () => {
  const address = {
    streetNumber: '123',
    route: 'Main Street',
    subPremise: 'Apt 4B',
    locality: 'San Francisco',
    administrativeAreaLevel1: 'CA',
    postalCode: '94102'
  };

  try {
    const result = await DoorstepAI.startDeliveryByAddress(
      address,
      'delivery_12345'
    );
    console.log('✅ Address delivery started:', result);
  } catch (error) {
    console.error('❌ Address delivery failed:', error);
  }
};

Delivery Events

Track important delivery milestones using event reporting:

Proof of Delivery (POD) Events

// When driver starts taking a photo for proof of delivery
const reportPODStart = async () => {
  try {
    const result = await DoorstepAI.newEvent(
      'taking_pod',
      'delivery_12345'
    );
    console.log('POD capture initiated:', result);
  } catch (error) {
    console.error('POD capture failed:', error);
  }
};

// When proof of delivery photo is captured
const reportPODCompleted = async () => {
  try {
    const result = await DoorstepAI.newEvent(
      'pod_captured',
      'delivery_12345'
    );
    console.log('POD captured successfully:', result);
  } catch (error) {
    console.error('POD capture failed:', error);
  }
};

Stopping Delivery Tracking

Stop tracking when the delivery is complete:

const stopDelivery = async () => {
  try {
    await DoorstepAI.stopDelivery('delivery_12345');
    console.log('🛑 Delivery tracking stopped');
  } catch (error) {
    console.error('❌ Error stopping delivery:', error);
  }
};

Address Types Reference

AddressType Interface

type AddressType = {
  streetNumber: string;
  route: string;
  subPremise: string;
  locality: string;
  administrativeAreaLevel1: string;
  postalCode: string;
};

Usage Examples

// Minimal address
const simpleAddress = {
  streetNumber: '456',
  route: 'Oak Avenue',
  subPremise: '',
  locality: 'Oakland',
  administrativeAreaLevel1: 'CA',
  postalCode: '94610'
};

// Complete address with apartment
const detailedAddress = {
  streetNumber: '789',
  route: 'Pine Street',
  subPremise: 'Suite 100',
  locality: 'Berkeley',
  administrativeAreaLevel1: 'California',
  postalCode: '94704'
};

Best Practices

1. Error Handling

Always implement proper error handling for SDK methods:

const startDeliveryWithErrorHandling = async (placeID, deliveryId) => {
  try {
    const result = await DoorstepAI.startDeliveryByPlaceID(placeID, deliveryId);
    // handle success
  } catch (error) {
    // handle error
  }
};

2. Lifecycle Management

Handle app lifecycle changes appropriately:

import React, { useEffect } from 'react';
import { AppState } from 'react-native';

const DeliveryManager = () => {
  useEffect(() => {
    const handleAppStateChange = (nextAppState) => {
      if (nextAppState === 'background') {
        // SDK automatically handles background processing
        console.log('📱 App entered background - SDK continues tracking');
      } else if (nextAppState === 'active') {
        console.log('📱 App returned to foreground');
      }
    };

    const subscription = AppState.addEventListener('change', handleAppStateChange);
    return () => subscription?.remove();
  }, []);

  // Your delivery management logic
};

3. Permission Handling

The RootDoorstepAI component automatically handles permission requests, but you can also handle them manually:

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

const requestPermissions = async () => {
  if (Platform.OS === 'android') {
    try {
      const permissionsToRequest = [
        PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
        PermissionsAndroid.PERMISSIONS.ACTIVITY_RECOGNITION,
      ];

      // Add background location permission for Android 10+ (API 29+)
      if (Platform.Version >= 29) {
        permissionsToRequest.push(PermissionsAndroid.PERMISSIONS.ACCESS_BACKGROUND_LOCATION);
      }

      const granted = await PermissionsAndroid.requestMultiple(permissionsToRequest);

      if (
        granted[PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION] ===
          PermissionsAndroid.RESULTS.GRANTED &&
        granted[PermissionsAndroid.PERMISSIONS.ACTIVITY_RECOGNITION] ===
          PermissionsAndroid.RESULTS.GRANTED
      ) {
        console.log('✅ Required Android permissions granted');
        
        // Check if background location was requested and granted
        if (Platform.Version >= 29 && 
            granted[PermissionsAndroid.PERMISSIONS.ACCESS_BACKGROUND_LOCATION] ===
            PermissionsAndroid.RESULTS.GRANTED) {
          console.log('✅ Background location permission granted');
        }
      } else {
        console.warn('❌ One or more required Android permissions denied');
      }
    } catch (err) {
      console.warn('❌ Error requesting Android permissions:', err);
    }
  } else if (Platform.OS === 'ios') {
    console.log('📱 iOS: Ensure location and motion usage descriptions are in Info.plist');
  }
};

Next Steps

Now that you have the SDK installed and configured:

1. 📚 Learn SDK Usage - Initialize and use the SDK
2. 💡 View Examples - See complete implementation examples