@prosquad/react-native-sdk

Android-only React Native SDK that embeds the Prosquad rider delivery flow into your app. The delivery UI runs in a full-screen native WebView with native integrations for location tracking, camera, QR scanning, and push notifications. Authentication is handled internally via OTP — no external auth token is needed.

Requirements

• React Native >= 0.60.0
• Android only (minSdk 24 / Android 7.0)

Installation

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

The library supports React Native autolinking — no manual native setup is required.

Android Permissions

The SDK declares the following permissions in its manifest (merged automatically):

• INTERNET
• ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION / ACCESS_BACKGROUND_LOCATION
• CAMERA
• FOREGROUND_SERVICE (location)
• POST_NOTIFICATIONS

Your app must request runtime permissions for location, camera, and notifications as appropriate.

Push Notifications (Firebase)

The SDK does not include Firebase itself. Your host app should integrate @react-native-firebase/messaging and forward notifications to the SDK (see usage below).

Usage

import * as ProsquadSDK from '@prosquad/react-native-sdk';

Launch the delivery flow

await ProsquadSDK.launch(
  {
    eid: 'your-enterprise-id',
    phoneNumber: '+919876543210',
    hostUserId: 'user-123',
    riderName: 'John Doe',       // displayed in the delivery UI
    city: 'Bangalore',
  },
  {
    onOrderComplete: (orderId, status) => {
      console.log(`Order ${orderId} completed with status: ${status}`);
    },
    onClose: () => {
      console.log('Delivery flow closed');
    },
    onNotificationReceived: (type, data) => {
      console.log('Notification received:', type, data);
    },
  },
);

Register FCM token

import messaging from '@react-native-firebase/messaging';

const token = await messaging().getToken();
await ProsquadSDK.registerDeviceToken(token);

Handle push notifications

// Background/quit handler
messaging().setBackgroundMessageHandler(async (remoteMessage) => {
  const handled = await ProsquadSDK.handleNotification(remoteMessage.data);
  if (handled) {
    await ProsquadSDK.showNotification({
      title: remoteMessage.notification?.title ?? 'New Order',
      body: remoteMessage.notification?.body ?? '',
      data: remoteMessage.data,
    });
  }
});

// Foreground handler
messaging().onMessage(async (remoteMessage) => {
  const handled = await ProsquadSDK.handleNotification(remoteMessage.data);
  if (handled) {
    await ProsquadSDK.showNotification({
      title: remoteMessage.notification?.title ?? 'New Order',
      body: remoteMessage.notification?.body ?? '',
      data: remoteMessage.data,
    });
  }
});

handleNotification returns true if the notification belongs to Prosquad (whitelisted types: order_assigned, batched_order_assigned, order_available, order_ready_pickup, auto_logout). If it returns false, your app should handle the notification itself.

Query active order status

const status = await ProsquadSDK.getActiveOrderStatus();
if (status) {
  console.log(`Active order: ${status.clientId}, state: ${status.orderState}`);
}

Crash reports (0.8.0+)

The native SDK reports its own errors to Prosquad's Sentry project over plain HTTP. It does not use the Sentry library, so it cannot collide with a Sentry or Crashlytics setup in your app and adds no io.sentry dependency. An uncaught exception in SDK code is recorded, then handed to the handler that was installed before it; your app still crashes and your reporter still sees it.

What is sent: the exception and stack trace, your package name and version, the enterprise id, the host user id, the SDK version, the device model and OS version. Never sent: phone number, location, photos.

Play Console: crash logs go to sentry.io. Add Crash logs to your app's Data safety form if it is not already there.

To mirror SDK errors into your own tool, pass onError in the listeners.

API Reference

| Function | Returns | Description | |----------|---------|-------------| | launch(config, listeners?) | Promise<void> | Opens the full-screen delivery WebView | | registerDeviceToken(token) | Promise<void> | Registers an FCM token with the Prosquad backend | | handleNotification(data) | Promise<boolean> | Forwards a push notification to the SDK; returns true if handled | | showNotification(options) | Promise<void> | Shows a local notification with the Prosquad order alert sound | | getActiveOrderStatus() | Promise<{clientId, orderState} \| null> | Returns current active order info, or null | | isOverlayPermissionGranted() | Promise<boolean> | Whether "Display over other apps" is granted | | requestOverlayPermission() | Promise<void> | Opens the system settings screen for that permission | | startOrderOverlay() | Promise<boolean> | Starts the floating order overlay; false if the permission is missing | | stopOrderOverlay() | Promise<void> | Removes the floating order overlay |

The SDK arms the overlay by itself once the permission exists — the four overlay functions are only needed to check it, prompt for it, or opt out.

ProsquadLaunchConfig

| Field | Type | Required | Description | |-------|------|----------|-------------| | eid | string | Yes | Enterprise ID | | phoneNumber | string | Yes | Rider's phone number (used for OTP auth) | | hostUserId | string | Yes | User ID in the host app | | riderName | string | No | Rider's display name; resolved from the backend after auth if omitted | | city | string | Yes | Rider's city | | theme | ProsquadTheme | No | White-label branding for the SDK's native screens, overlay and web UI | | env | 'dev' \| 'prod' | No | Backend to talk to. Defaults to 'prod'; unrecognised values are treated as 'prod' |

env is chosen per launch, so one build can point at either backend — you no longer need a separately built AAR to test against dev.

ProsquadTheme

All fields optional. Colors should be #RRGGBB or #AARRGGBB.

| Field | Type | Description | |-------|------|-------------| | companyName | string | Brand name; shown as the brand line on the floating order overlay | | brandName | string | Alias for companyName, kept for older host code | | logoUrl | string | Logo shown in the delivery UI | | splashIconUrl | string | Icon shown on the SDK splash | | primaryColor | string | Primary brand color | | secondaryColor | string | Secondary brand color | | accentColor | string | Alias for secondaryColor, kept for older host code | | backgroundColor | string | Background color | | textColor | string | Body text color |

ProsquadEventListeners

| Callback | Signature | Description | |----------|-----------|-------------| | onOrderComplete | (orderId: string, status: string) => void | Fired when a delivery is completed | | onClose | () => void | Fired when the rider closes the delivery UI | | onNotificationReceived | (type: string, data: Record<string, string>) => void | Fired when a Prosquad notification arrives while the UI is closed | | onError | (error: ProsquadSdkError) => void | Fired when the SDK records an internal error (0.8.0+). The SDK already reports it; use this to mirror it into your own crash tool |

License

MIT