Skip to Content
DevelopersSDKsReact Native SDKGeofencing & location

Geofencing & location

Geofencing lets you react when a customer enters or leaves the area around one of your outlets — for example to fire a “Welcome back” in-app message or attribute a visit. The React Native SDK bridges to the dedicated native AegisLocation module (an RCTEventEmitter on iOS, an RCTDeviceEventEmitter on Android), which delegates to native iOS CoreLocation (which monitors up to 20 regions via nearest-N selection) and Android Play Services geofencing (no region cap).

Geofencing is opt-in. The Active Reach library declares no location permission of its own — so apps that don’t use geofencing never trigger a location prompt or disclosure. When you do use it, your app owns the location permission: the SDK never requests authorization on the user’s behalf. You must request platform permission yourself before calling startMonitoring.

Permissions are the host app’s responsibility

Because the library ships no location permission, you must add the platform requirements to your app:

iOS

  • Add the usage-string keys to Info.plist (e.g. NSLocationWhenInUseUsageDescription, and NSLocationAlwaysAndWhenInUseUsageDescription if you need monitoring while backgrounded).
  • Request CoreLocation authorization at runtime before you start monitoring.

Android

  • Declare ACCESS_FINE_LOCATION in your app’s AndroidManifest.xml. For API 29+ also declare ACCESS_BACKGROUND_LOCATION if you need geofences to fire while the app is backgrounded.
  • Add the play-services-location dependency to your app.
  • Request the location permission at runtime before you start monitoring.

Setup

Request platform location permission

Use your platform permission flow (e.g. PermissionsAndroid on Android, a CoreLocation authorization request on iOS) and confirm the customer granted it. Do not proceed until permission is granted.

Start monitoring your outlet geofences

Call startMonitoring with the set of geofences you want to watch — typically derived from your outlet list, fetched server-side at SDK init. Each Geofence is { id, label, latitude, longitude, radiusMeters?, metadata? }.

import { startMonitoring } from '@active-reach/react-native-sdk';
 
await startMonitoring([
  {
    id: 'outlet_koramangala',
    label: 'Koramangala',
    latitude: 12.9352,
    longitude: 77.6245,
    radiusMeters: 150,
    metadata: { outlet_code: 'BLR-01' },
  },
  {
    id: 'outlet_indiranagar',
    label: 'Indiranagar',
    latitude: 12.9719,
    longitude: 77.6412,
  },
]);

Subscribe to entry / exit events

Register a listener with onGeofenceEvent. It returns an unsubscribe function. The eventName is either geofence.entered or geofence.exited.

import { onGeofenceEvent } from '@active-reach/react-native-sdk';
 
const unsubscribe = onGeofenceEvent((event) => {
  if (event.eventName === 'geofence.entered') {
    console.log('Customer entered', event.geofenceLabel);
  } else {
    console.log('Customer left', event.geofenceLabel);
  }
});

Each event is a GeofenceEvent:

export interface GeofenceEvent {
  eventName: 'geofence.entered' | 'geofence.exited';
  geofenceId: string;
  geofenceLabel: string;
  geofenceLatitude: number;
  geofenceLongitude: number;
  geofenceRadiusMeters: number;
  metadata: Record<string, string>;
}

Stop monitoring on logout or opt-out

Tear down all geofence monitoring when the customer logs out or opts out of location features, and remember to call the unsubscribe function returned by onGeofenceEvent.

import { stopMonitoring } from '@active-reach/react-native-sdk';
 
await stopMonitoring();
unsubscribe();

Geofencing requires the native module linked — run pod install for iOS and let Android autolink, then rebuild. When the module is missing, startMonitoring and onGeofenceEvent log a warning and become safe no-ops, so shared JS code stays runnable on unlinked builds.

What’s next

Push primerQuickstart