Tracking Functions

Core functions for managing background location tracking sessions. All functions are async and handle native module unavailability gracefully by logging a warning and returning safe fallback values.

import {
  startTracking,
  stopTracking,
  isTracking,
  getLocations,
  clearTrip,
  updateNotification,
} from '@gabriel-sisjr/react-native-background-location';

---

startTracking

Starts location tracking in the background for a specific trip. When the native module is not available (e.g., running in a simulator without the module linked), logs a warning and returns a fallback tripId without crashing.

Platform: Android and iOS

Signature

function startTracking(
  tripIdOrOptions?: string | TrackingOptions,
  options?: TrackingOptions
): Promise<string>

Overloads

The function supports two calling patterns:

Pattern	Description
startTracking()	Auto-generates a tripId, uses default options
startTracking(options)	Auto-generates a tripId, uses provided options
startTracking(tripId)	Uses provided tripId, default options
startTracking(tripId, options)	Uses provided tripId and options

Parameters

Name	Type	Required	Description
tripIdOrOptions	string | TrackingOptions	No	Either a trip identifier string or tracking configuration options. If omitted, a new tripId is generated by the native module.
options	TrackingOptions	No	Tracking configuration options. Only used when the first parameter is a string tripId.

Return Value

Promise<string> — Resolves to the effective tripId (either the provided one or the auto-generated one).

Note: When the native module is unavailable, returns the provided tripId or a fallback simulator-trip-{timestamp} string.

Usage

// Auto-generated tripId with default options
const tripId = await startTracking();

// Auto-generated tripId with custom options
const tripId = await startTracking({
  accuracy: LocationAccuracy.HIGH_ACCURACY,
  updateInterval: 10000,
  distanceFilter: 50,
  notificationOptions: {
    title: 'Tracking Active',
    text: 'Your location is being recorded',
  },
});

// Explicit tripId
const tripId = await startTracking('trip-abc-123');

// Explicit tripId with options
const tripId = await startTracking('trip-abc-123', {
  accuracy: LocationAccuracy.BALANCED_POWER_ACCURACY,
  fastestInterval: 5000,
});

---

stopTracking

Stops all location tracking and terminates the background service.

Platform: Android and iOS

Signature

function stopTracking(): Promise<void>

Parameters

None.

Return Value

Promise<void> — Resolves when tracking is fully stopped.

Usage

await stopTracking();

---

isTracking

Checks whether location tracking is currently active.

Platform: Android and iOS

Signature

function isTracking(): Promise<TrackingStatus>

Parameters

None.

Return Value

Promise<TrackingStatus> — Resolves to an object describing the current tracking state.

interface TrackingStatus {
  active: boolean;
  tripId?: string;
}

Property	Type	Description
active	boolean	Whether tracking is currently running
tripId	string | undefined	The current trip identifier, present only when active is true

Note: When the native module is unavailable, returns { active: false }.

Usage

const status = await isTracking();

if (status.active) {
  console.log('Currently tracking trip:', status.tripId);
} else {
  console.log('Not tracking');
}

---

getLocations

Retrieves all stored location points for a specific trip from the local database.

Platform: Android and iOS

Signature

function getLocations(tripId: string): Promise<Coords[]>

Parameters

Name	Type	Required	Description
tripId	string	Yes	The trip identifier to retrieve locations for

Return Value

Promise<Coords[]> — Array of location coordinates with extended location data.

See the Types reference for the full Coords interface.

Note: When the native module is unavailable, returns an empty array.

Usage

const locations = await getLocations('trip-abc-123');
console.log(`Retrieved ${locations.length} locations`);

locations.forEach((loc) => {
  console.log(`${loc.latitude}, ${loc.longitude} at ${loc.timestamp}`);
});

---

clearTrip

Clears all stored location data for a specific trip from the local database.

Platform: Android and iOS

Signature

function clearTrip(tripId: string): Promise<void>

Parameters

Name	Type	Required	Description
tripId	string	Yes	The trip identifier whose data should be deleted

Return Value

Promise<void> — Resolves when the data has been cleared.

Usage

await clearTrip('trip-abc-123');
console.log('Trip data cleared');

---

updateNotification

Updates the foreground service notification content while tracking is active. Dynamic updates are transient and do not persist across service restarts.

Platform: Android and iOS

Signature

function updateNotification(title: string, text: string): Promise<void>

Parameters

Name	Type	Required	Description
title	string	Yes	New notification title
text	string	Yes	New notification body text

Return Value

Promise<void> — Resolves when the notification has been updated.

Important: Changes made with updateNotification are transient. If the service restarts (e.g., due to crash recovery), the notification reverts to the configuration provided in TrackingOptions.notificationOptions when startTracking was called.

Usage

// Update notification with dynamic trip info
await updateNotification(
  'Trip in Progress',
  `${distanceTraveled} km traveled`
);