Skip to main content

Installation and quick start

This page takes you from an empty React Native project to location points arriving on a backend. Expect about 15 minutes.

Requirements​

RequirementVersion
React NativeNew Architecture enabled (TurboModules). Tested on 0.88.
AndroidminSdkVersion 24 or higher, compileSdkVersion 36 recommended, Java 17
iOSiOS 15.1 or higher, CocoaPods
Build typeDebug for the Evaluation edition. Release builds need a license.
New Architecture only

The package is a TurboModule. If your app still runs the old architecture, enable the New Architecture first (newArchEnabled=true in android/gradle.properties, and RCT_NEW_ARCH_ENABLED=1 when running pod install on older React Native versions).

1. Install​

npm install react-native-background-location-pro-eval
# or
yarn add react-native-background-location-pro-eval

Then install the iOS pods:

cd ios && pod install && cd ..

Autolinking registers the module on both platforms. You do not need to edit MainApplication, AppDelegate, or register any package by hand.

2. Add the platform configuration​

Each platform needs a few permission and background entries before tracking can work:

  • Android setup: most permissions merge automatically; you only handle runtime prompts and, optionally, cleartext HTTP for local testing.
  • iOS setup: add UIBackgroundModes, BGTaskSchedulerPermittedIdentifiers and the usage strings to Info.plist.

3. Run a backend that accepts points​

The tracker sends batches with POST {serverUrl}/api/location/track. For a first test, this 20-line Node server is enough:

server.js
const http = require('http');

http
  .createServer((req, res) => {
    if (req.method === 'POST' && req.url === '/api/location/track') {
      let body = '';
      req.on('data', chunk => (body += chunk));
      req.on('end', () => {
        const batch = JSON.parse(body);
        console.log(`batch ${batch.batchId}: ${batch.points.length} points`);
        res.writeHead(200, {'Content-Type': 'application/json'});
        res.end(JSON.stringify({ok: true}));
      });
      return;
    }
    res.writeHead(404);
    res.end();
  })
  .listen(3000, () => console.log('listening on :3000'));
node server.js

The full request format is in Offline tracking and sync.

Reaching your laptop from a device
  • Android emulator: use http://10.0.2.2:3000.
  • iOS simulator: use http://localhost:3000.
  • Physical device: use your computer's LAN IP (for example http://192.168.1.20:3000), or a tunnel such as ngrok for HTTPS.

Plain http:// URLs need the cleartext exceptions described in the platform setup pages.

4. Start tracking​

App.tsx
import React, {useEffect, useState} from 'react';
import {Button, SafeAreaView, Text} from 'react-native';
import LocationTracker, {
  type LocationEvent,
  type SyncEvent,
} from 'react-native-background-location-pro-eval';

const SERVER_URL = 'http://10.0.2.2:3000'; // see the tip above

export default function App() {
  const [last, setLast] = useState<LocationEvent | null>(null);
  const [sync, setSync] = useState<SyncEvent | null>(null);

  useEffect(() => {
    const locationSub = LocationTracker.onLocationUpdate(setLast);
    const syncSub = LocationTracker.onSyncStatus(setSync);
    return () => {
      locationSub.remove();
      syncSub.remove();
    };
  }, []);

  return (
    <SafeAreaView style={{padding: 24, gap: 12}}>
      <Button
        title="1. Grant location permission"
        onPress={() => LocationTracker.requestLocationPermission(true)}
      />
      <Button
        title="2. Start tracking"
        onPress={() => LocationTracker.startTracking(SERVER_URL)}
      />
      <Button title="Stop tracking" onPress={() => LocationTracker.stopTracking()} />

      <Text>
        Last point: {last ? `${last.latitude.toFixed(5)}, ${last.longitude.toFixed(5)}` : 'none yet'}
      </Text>
      <Text>Pending upload: {sync?.pending ?? 0}</Text>
      <Text>Synced: {sync?.synced ?? 0}</Text>
      <Text>Status: {sync?.message ?? LocationTracker.getStatus().message}</Text>
    </SafeAreaView>
  );
}

5. Verify​

  1. Tap Grant location permission and accept the prompts.
  2. Tap Start tracking.
  3. Walk around, or simulate a route (Android emulator: Extended controls > Location > Routes; iOS simulator: Features > Location > City Run).
  4. Your server logs batch ...: N points, and the app shows Synced increasing.
  5. Background the app, or swipe it away. Points keep arriving.

If nothing arrives, call LocationTracker.getStatus() and check the troubleshooting guide. In particular, check that buildTier is 'debug'.

Next steps​