@crewmint/geolocation

React Native adapter for the Crewmint GeoEngine Android SDK. It provides background location tracking, geofencing, permission diagnostics, local offline queue introspection, and event subscriptions through a typed TypeScript facade.

Current platform support:

| Platform | Status | | --- | --- | | Android | Supported, API 26+ | | iOS | Not implemented in this release. Calls reject with PlatformNotSupportedError. |

Features

• Android foreground-service location tracking
• On-demand current location
• Geofence registration and transition events
• Permission state snapshots
• Offline queue sync trigger and status
• Live event subscriptions for location, motion, geofence, permission, and sync changes
• Commercial signed license.geo validation in release builds

Requirements

| Tool | Minimum | | --- | --- | | React Native | 0.80+ | | Node.js | 20+ | | Android minSdk | 26 | | Android compileSdk | 36 | | Java | 17 |

Installation

npm install @crewmint/geolocation

The package autolinks through React Native. The Android wrapper resolves the native SDK from Maven Central when used as a published package.

Android License File

Release builds require a signed license file named license.geo.

Place it here in your app:

android/app/src/main/assets/license.geo

Debug builds may use the SDK debug bypass policy. Release builds without a valid license remain uninitialized and operational API calls reject with a licensing error.

Permissions

Request runtime permissions before starting tracking. At minimum:

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

export async function requestGeoEnginePermissions() {
  if (Platform.OS !== 'android') return;

  await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION);

  if (Platform.Version >= 29) {
    await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.ACCESS_BACKGROUND_LOCATION);
  }

  if (Platform.Version >= 33) {
    await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS);
  }
}

Foreground/background permission UX must be owned by your app. The SDK reports permission state; it does not display permission screens.

Quick Start

import { Geolocation } from '@crewmint/geolocation';

async function startTracking() {
  const status = await Geolocation.getStatus();

  if (!status.initialized) {
    throw new Error(`GeoEngine is not initialized: ${status.initializationState}`);
  }

  await Geolocation.start({
    interval: 15000,
    fastestInterval: 5000,
    priority: 'HIGH_ACCURACY',
    stopOnTerminate: false,
    startOnBoot: true,
  });
}

Receive Events

import { useEffect } from 'react';
import { Geolocation } from '@crewmint/geolocation';

export function useGeoEngineEvents() {
  useEffect(() => {
    const location = Geolocation.onLocationUpdate((fix) => {
      console.log('location', fix.latitude, fix.longitude, fix.accuracy);
    });

    const geofence = Geolocation.onGeofenceTransition((event) => {
      console.log('geofence', event.identifier, event.transition);
    });

    const sync = Geolocation.onSyncStatusChange((event) => {
      console.log('sync', event.state);
    });

    return () => {
      location.remove();
      geofence.remove();
      sync.remove();
    };
  }, []);
}

Stop Tracking

await Geolocation.stop();

API Surface

The package exports:

• Geolocation.start(config)
• Geolocation.stop()
• Geolocation.getCurrentPosition()
• Geolocation.addGeofence(geofence)
• Geolocation.removeGeofence(identifier)
• Geolocation.getPermissionSnapshot()
• Geolocation.syncNow()
• Geolocation.getTrackingState()
• Geolocation.isTracking()
• Geolocation.getLastKnownLocation()
• Geolocation.getGeofences()
• Geolocation.getSyncStatus()
• Geolocation.getStatus()
• Geolocation.onLocationUpdate(callback)
• Geolocation.onMotionChange(callback)
• Geolocation.onGeofenceTransition(callback)
• Geolocation.onPermissionChange(callback)
• Geolocation.onSyncStatusChange(callback)

All operational APIs are Android-only in this release.

Example Application

The example app at react-native-wrapper/example is the canonical playground. It demonstrates:

• SDK and license status
• Permission snapshot inspection
• Start/stop tracking
• Current and streamed locations
• Geofence add/remove and transition logs
• Sync status and manual sync
• Live event console
• Debug diagnostics

Run it with:

cd react-native-wrapper/example
npm install
npm run android

For release testing, copy a signed license.geo into:

react-native-wrapper/example/android/app/src/main/assets/license.geo

Troubleshooting

| Symptom | Likely Cause | Fix | | --- | --- | --- | | LICENSE_NOT_FOUND | Missing release license | Add android/app/src/main/assets/license.geo. | | INVALID_SIGNATURE only after minification | Stale package copy or missing consumer ProGuard rules | Reinstall the package and ensure the AAR includes proguard.txt with GeoEngine license keep rules. | | PACKAGE_MISMATCH | License was issued for another Android application ID | Generate a license for the exact release package name. | | NOT_INITIALIZED | Initialization failed or license invalid | Call Geolocation.getStatus() and inspect initializationState. | | Foreground service does not start | Missing notification/location permissions or Android FGS restriction | Request runtime permissions and test from a user-initiated action. | | iOS call rejects | iOS is not implemented in this release | Gate calls with Platform.OS === 'android'. |

Package Verification

Before publishing:

npm run build
npm pack
npm run verify

The verification script checks packed files, typings, package installability, and accidental native binary/debug content.

Documentation

• React Native API docs: docs/api/react-native
• React Native quickstart: docs/quickstart/react-native.md
• Troubleshooting: docs/troubleshooting/README.md
• Licensing lifecycle: docs/customer-license-workflow.md

License

Commercial. Contact Crewmint for license generation and production activation.