React Native Background Geolocation

https://transistorsoft.github.io/react-native-background-geolocation
Admin
React Native Background Geolocation is a powerful library for tracking user location, motion...
Tokens:89,638
Snippets:890
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Add Geofence and Start Monitoring

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

Demonstrates how to add a geofence, listen for geofence events, and configure the plugin to start monitoring geofences.

```javascript
BackgroundGeolocation.addGeofence({
  notifyOnExit: true,
  radius: 200,
  identifier: "ZONE_OF_INTEREST",
  latitude: 37.234232,
  longitude: 42.234234
});

// Listen to geofence events.
BackgroundGeolocation.onGeofence((event) => {
  console.log("[onGeofence] -  ", event);
});

// Configure the plugin
BackgroundGeolocation.ready({
  url: "http://my.server.com",
  autoSync: true
}).then(((state) => {
  // Start monitoring geofences.
  BackgroundGeolocation.startGeofences();
});

```

--------------------------------

### Fetching Logs Example

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/logger.html

Example demonstrating how to access the Logger API and fetch logs.

```APIDOC
## Fetching the Logs

Logs can be fetched from the SDK in three ways:

1. **getLog**
2. **emailLog**
3. **uploadLog**

### Example Usage

```javascript
let Logger = BackgroundGeolocation.logger;
let log = await Logger.getLog();
```
```

--------------------------------

### Ready and Start Tracking

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

This section outlines the essential steps to initialize and begin location tracking with the BackgroundGeolocation SDK. It includes calling the `ready` method with configuration options and then invoking the `start` method.

```APIDOC
## Initialization and Tracking

There are three main steps to using `BackgroundGeolocation`:
  1. Wire up event-listeners.
  2. ready the SDK.
  3. start tracking.

### `ready(config, callback)`
Initializes the SDK with the provided configuration and executes a callback upon successful readiness.

#### Parameters
*   **config** (object) - Required - Geolocation configuration object.
    *   `desiredAccuracy` (number) - Desired accuracy level (e.g., `BackgroundGeolocation.DESIRED_ACCURACY_HIGH`).
    *   `distanceFilter` (number) - Minimum distance in meters to trigger a location update.
    *   `stopTimeout` (number) - Timeout in seconds before stopping tracking when stationary.
    *   `debug` (boolean) - Enable debug logs and sounds.
    *   `logLevel` (number) - Verbosity of logs (e.g., `BackgroundGeolocation.LOG_LEVEL_VERBOSE`).
    *   `stopOnTerminate` (boolean) - Allow background-service to continue tracking when app is terminated.
    *   `startOnBoot` (boolean) - Automatically start tracking when the device powers up.
    *   `url` (string) - URL for HTTP synchronization.
    *   `batchSync` (boolean) - Sync locations in a single HTTP request.
    *   `autoSync` (boolean) - Sync each location to the server as it arrives.
    *   `headers` (object) - Optional HTTP headers for synchronization.
    *   `params` (object) - Optional HTTP parameters for synchronization.
*   **callback** (function) - Function executed after the SDK is ready. Receives a `state` object.

### `start(callback)`
Starts the background location tracking service.

#### Parameters
*   **callback** (function) - Optional function executed upon successful start.

### Warning
Do not execute any API method which will require accessing location-services until the callback to `ready` executes (eg: `getCurrentPosition`, `watchPosition`, `start`).

### Example Usage
```javascript
BackgroundGeolocation.ready({
  // Geolocation Config
  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10,
  // Activity Recognition
  stopTimeout: 1,
  // Application config
  debug: true,              // <-- enable this hear debug sounds.
  logLevel: BackgroundGeolocation.LOG_LEVEL_VERBOSE,
  stopOnTerminate: false,   // <-- Allow the background-service to continue tracking when app terminated.
  startOnBoot: true,        // <-- Auto start tracking when device is powered-up.
  // HTTP / SQLite config
  url: "http://yourserver.com/locations",
  batchSync: false,       // <-- Set true to sync locations to server in a single HTTP request.
  autoSync: true,         // <-- Set true to sync each location to server as it arrives.
  headers: {              // <-- Optional HTTP headers
    "X-FOO": "bar"
  },
  params: {               // <-- Optional HTTP params
    "auth_token": "maybe_your_server_authenticates_via_token_YES?"
  }
}, (state) => {
  console.log("- BackgroundGeolocation is configured and ready: ", state.enabled);

  if (!state.enabled) {
    // Start tracking!
    BackgroundGeolocation.start(function() {
      console.log("- Start success");
    });
  }
});
```
```

--------------------------------

### Example Log Data

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/state.html

This snippet displays example log output from the plugin, showing service startup, activity recognition, and HTTP requests.

```log
09-19 11:12:18.716 ╔═════════════════════════════════════════════
09-19 11:12:18.716 ║ BackgroundGeolocation Service started
09-19 11:12:18.716 ╠═════════════════════════════════════════════
09-19 11:12:18.723 [c.t.l.BackgroundGeolocationService d]
09-19 11:12:18.723   ✅  Started in foreground
09-19 11:12:18.737 [c.t.l.ActivityRecognitionService a]
09-19 11:12:18.737   🎾  Start activity updates: 10000
09-19 11:12:18.761 [c.t.l.BackgroundGeolocationService k]
09-19 11:12:18.761   🔴  Stop heartbeat
09-19 11:12:18.768 [c.t.l.BackgroundGeolocationService a]
09-19 11:12:18.768   🎾  Start heartbeat (60)
09-19 11:12:18.778 [c.t.l.BackgroundGeolocationService a]
09-19 11:12:18.778   🔵  setPace: null → false
09-19 11:12:18.781 [c.t.l.adapter.TSConfig c] ℹ️   Persist config
09-19 11:12:18.794 [c.t.locationmanager.util.b a]
09-19 11:12:18.794   ℹ️  LocationAuthorization: Permission granted
09-19 11:12:18.842 [c.t.l.http.HttpService flush]
09-19 11:12:18.842 ╔═════════════════════════════════════════════
09-19 11:12:18.842 ║ HTTP Service
09-19 11:12:18.842 ╠═════════════════════════════════════════════
09-19 11:12:19.000 [c.t.l.BackgroundGeolocationService onActivityRecognitionResult] still (100%)
09-19 11:12:21.314 [c.t.l.l.SingleLocationRequest$2 onLocationResult]
09-19 11:12:21.314 ╔═════════════════════════════════════════════
09-19 11:12:21.314 ║ SingleLocationRequest: 1
09-19 11:12:21.314 ╠═════════════════════════════════════════════
09-19 11:12:21.314 ╟─ 📍  Location[fused 45.519239,-73.617058 hAcc=15]999923706055 vAcc=2 sAcc=??? bAcc=???
09-19 11:12:21.327 [c.t.l.l.TSLocationManager onSingleLocationResult]
09-19 11:12:21.327   🔵  Acquired motionchange position, isMoving: false
09-19 11:12:21.342 [c.t.l.l.TSLocationManager a] 15.243
09-19 11:12:21.405 [c.t.locationmanager.data.a.c persist]
09-19 11:12:21.405   ✅  INSERT: bca5acc8-e358-4d8f-827f-b8c0d556b7bb
09-19 11:12:21.423 [c.t.l.http.HttpService flush]
09-19 11:12:21.423 ╔═════════════════════════════════════════════
09-19 11:12:21.423 ║ HTTP Service
09-19 11:12:21.423 ╠═════════════════════════════════════════════
09-19 11:12:21.446 [c.t.locationmanager.data.a.c first]
09-19 11:12:21.446   ✅  Locked 1 records
09-19 11:12:21.454 [c.t.l.http.HttpService a]
09-19 11:12:21.454   🔵  HTTP POST: bca5acc8-e358-4d8f-827f-b8c0d556b7bb
09-19 11:12:22.083 [c.t.l.http.HttpService$a onResponse]
09-19 11:12:22.083   🔵  Response: 200
09-19 11:12:22.100 [c.t.locationmanager.data.a.c destroy]
09-19 11:12:22.100   ✅  DESTROY: bca5acc8-e358-4d8f-827f-b8c0d556b7bb
09-19 11:12:55.226 [c.t.l.BackgroundGeolocationService onActivityRecognitionResult] still (100%)
```

--------------------------------

### HTTP Request Example with Params

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/state.html

An example demonstrating how custom params are appended to the HTTP request body when sent to the server.

```http
POST /locations
 {
  "location": {
    "coords": {
      "latitude": 45.51927004945047,
      "longitude": -73.61650072045029
      .
      .
      .
    }
  },
  "user_id": 1234,  // <-- params appended to the data.
  "device_id": "abc123"
}

```

--------------------------------

### Configure Event Listeners, Ready SDK, and Start Tracking

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

This snippet demonstrates the three main steps for using the BackgroundGeolocation SDK: wiring up event listeners, calling the ready method with configuration, and starting location tracking. It includes handlers for location, motion change, HTTP responses, activity changes, and provider changes.

```javascript
//
// 1.  Wire up event-listeners
//

// This handler fires whenever bgGeo receives a location update.
BackgroundGeolocation.onLocation(location => {
  console.log("[location] ", location);
}, error => {
  console.log("[location] ERROR: ", error);
});

// This handler fires when movement states changes (stationary->moving; moving->stationary)
BackgroundGeolocation.onMotionChange(location => {
  console.log("[motionchange] ", location);
});

// This handler fires on HTTP responses
BackgroundGeolocation.onHttp(response => {
  console.log("[http] ", response);
});

// This event fires when a change in motion activity is detected
BackgroundGeolocation.onActivityChange(activityEvent => {
  console.log("[activitychange] ", activityEvent);
});

// This event fires when the user toggles location-services authorization
BackgroundGeolocation.onProviderChange(providerEvent => {
  console.log("[providerchange] ", providerEvent);
});

//
// 2.  Execute #ready method (required)
//
BackgroundGeolocation.ready({
  // Geolocation Config
  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10,
  // Activity Recognition
  stopTimeout: 1,
  // Application config
  debug: true,              // <-- enable this hear debug sounds.
  logLevel: BackgroundGeolocation.LOG_LEVEL_VERBOSE,
  stopOnTerminate: false,   // <-- Allow the background-service to continue tracking when app terminated.
  startOnBoot: true,        // <-- Auto start tracking when device is powered-up.
  // HTTP / SQLite config
  url: "http://yourserver.com/locations",
  batchSync: false,       // <-- Set true to sync locations to server in a single HTTP request.
  autoSync: true,         // <-- Set true to sync each location to server as it arrives.
  headers: {              // <-- Optional HTTP headers
    "X-FOO": "bar"
  },
  params: {               // <-- Optional HTTP params
    "auth_token": "maybe_your_server_authenticates_via_token_YES?"
  }
}, (state) => {
  console.log("- BackgroundGeolocation is configured and ready: ", state.enabled);

  if (!state.enabled) {
    //
    // 3. Start tracking!
    //
    BackgroundGeolocation.start(function() {
      console.log("- Start success");
    });
  }
});

```

--------------------------------

### Start Schedule

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

Initiates the configured schedule for location tracking. The plugin will automatically start or stop according to the schedule.

```javascript
BackgroundGeolocation.startSchedule.then((state) => {
  console.log("[startSchedule] success: ", state);
})

```

--------------------------------

### start

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

Enables location and geofence tracking. This is the primary method to turn on the SDK, initiating location fetches and background monitoring.

```APIDOC
## Static start
  * start(success?: (state: State) => void, error?: (error: string) => void): Promise<State>


  * Enable location + geofence tracking.
This is the SDK's power **ON** button. The plugin will initially start into its **stationary** state, fetching an initial location before turning off location services. Android will be monitoring its **Activity Recognition System** while iOS will create a stationary geofence around the current location.
### ⚠️ Note:
If you've configured a schedule, this method will override that schedule and engage tracking immediately. 

example
    ```
BackgroundGeolocation.start().then((state) => {
  console.log("[start] success - ", state);
});

```

### ℹ️ See also:
    * stop
    * startGeofences
    * 📘 Philosophy of Operation
#### Parameters
    * ##### Optional success: (state: State) => void
      *         * (state: State): void
        * #### Parameters
          * ##### state: State
#### Returns void
    * ##### Optional error: (error: string) => void
      *         * (error: string): void
        * #### Parameters
          * ##### error: string
#### Returns void
#### Returns Promise<State>
```

--------------------------------

### Promise API Example

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

Demonstrates the usage of the Promise API for initializing the BackgroundGeolocation plugin.

```APIDOC
## Promise API Example

### Description
This example shows how to use the Promise API to initialize the BackgroundGeolocation plugin and handle potential errors.

### Method
`BackgroundGeolocation.ready()`

### Parameters
- **`desiredAccuracy`** (number) - Optional - The desired accuracy for location updates.
- **`distanceFilter`** (number) - Optional - The minimum distance in meters to trigger a location update.

### Request Example
```javascript
BackgroundGeolocation.ready({
  desiredAccuracy: 0,
  distanceFilter: 50
}).then(state => {
  console.log("- BackgroundGeolocation is ready: ", state);
}).catch(error => {
  console.log("- BackgroundGeolocation error: ", error);
});
```

### Response
#### Success Response (state)
- **`state`** (object) - An object containing the current state of the BackgroundGeolocation plugin.

#### Error Response
- **`error`** (object) - An object containing error information if initialization fails.
```

--------------------------------

### Start Location and Geofence Tracking

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

Enable location and geofence tracking. This method initiates the SDK's tracking, starting with a stationary state and an initial location fetch.

```javascript
BackgroundGeolocation.start().then((state) => {
  console.log("[start] success - ", state);
});
```

--------------------------------

### RPC: Multiple Actions Example

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/httpevent.html

Execute multiple SDK commands sequentially by including them as separate entries in the `background_geolocation` array.

```json
{
  "background_geolocation": [
    ["start"],
    ["changePace", true]
  ]
}
```

--------------------------------

### HTTP Request Logging Example

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/state.html

Illustrates the log output when the SDK performs HTTP requests to upload location data.

```text
╔═════════════════════════════════════════════
║ LocationService: location
╠═════════════════════════════════════════════
╟─ 📍 Location[45.519199,-73.617054]
✅ INSERT: 70727f8b-df7d-48d0-acbd-15f10cacdf33
╔═════════════════════════════════════════════
║ HTTP Service
╠═════════════════════════════════════════════
✅ Locked 1 records
🔵 HTTP POST: 70727f8b-df7d-48d0-acbd-15f10cacdf33
🔵 Response: 200
✅ DESTROY: 70727f8b-df7d-48d0-acbd-15f10cacdf33

```

--------------------------------

### Constrain Log Records by Start Date

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/sqlquery.html

Fetch log records starting from a specific date using SQLQuery. The start date is provided as a Unix timestamp.

```javascript
let log = await BackgroundGeolocation.logger.getLog({
  start: Date.parse("2019-10-21 13:00")
});
```

--------------------------------

### Authorization Server Response Example (Flat)

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/authorization.html

An example of a flat JSON response structure from an authorization server, with direct access token, refresh token, and expiry keys.

```json
{
 "accessToken": "XXX.YYY.ZZZ",
 "refreshToken": "smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb",
 "expiry": 3900
}
```

--------------------------------

### Authorization Configuration Example

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/authorization.html

Demonstrates how to configure the authorization settings, including access token, refresh token, refresh URL, and refresh payload, when initializing the SDK.

```APIDOC
## Configuration 

example
    ```
let myToken = this.getMyAuthorizationToken();

BackgroundGeolocation.onAuthorization((event) => {
  if (event.success) {
    console.log("[authorization] ERROR: ", event.error);
  } else {
    console.log("[authorization] SUCCESS: ", event.response);
  }
});

BackgroundGeolocation.ready({
  url: "https://app.your.server.com/users/locations",
  autoSync: true,
  authorization: {
    strategy: "JWT",
    accessToken: myToken.accessToken,
    refreshToken: myToken.refreshToken,
    refreshUrl: "https://auth.your.server.com/tokens",
    refreshPayload: {
      the_refresh_token_field_name: "{refreshToken}"
    },
    expires: myToken.expiresAt
  }
});

```
```

--------------------------------

### HTTP Request Logging Example

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/httpevent.html

Observe the plugin's HTTP request activity in the logs for both iOS and Android platforms.

```text
╔═════════════════════════════════════════════
║ LocationService: location
╠═════════════════════════════════════════════
╟─ 📍 Location[45.519199,-73.617054]
✅ INSERT: 70727f8b-df7d-48d0-acbd-15f10cacdf33
╔═════════════════════════════════════════════
║ HTTP Service
╠═════════════════════════════════════════════
✅ Locked 1 records
🔵 HTTP POST: 70727f8b-df7d-48d0-acbd-15f10cacdf33
🔵 Response: 200
✅ DESTROY: 70727f8b-df7d-48d0-acbd-15f10cacdf33
```

--------------------------------

### DistanceFilter Elasticity Calculation Example

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/config.html

Demonstrates how the `distanceFilter` is automatically adjusted based on the device's speed. This example shows the calculation for biking speed.

```javascript
rounded_speed = round(7.7, 5)
=> 10
multiplier = rounded_speed / 5
=> 10 / 5 = 2
adjusted_distance_filter = multiplier * distanceFilter
=> 2 * 30 = 60 meters
```

--------------------------------

### Configure and Listen for HTTP Responses

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/httpevent.html

Configure the SDK with a URL for HTTP uploads and listen for responses using BackgroundGeolocation.onHttp. This example shows setting up URL, sync options, headers, and parameters.

```javascript
// Listen for HTTP responses.
BackgroundGeolocation.onHttp(response => {
  console.log("[http] response: ", response.success, response.status, response.responseText);
});

BackgroundGeolocation.ready({
  url: "https://my-server.com/locations",
  autoSync: true,
  autoSyncThreshold: 5,
  batchSync: true,
  maxBatchSize: 50,
  headers: {
    AUTHENTICATION_TOKEN: "23kasdlfkjlksjflkasdZIds"
  },
  params: {
    user_id: 1234
  },
  extras: {
    route_id: 8675309
  },
  locationsOrderDirection: "DESC",
  maxDaysToPersist: 14
}, state => {
  console.log("[ready] success: ", state);
});

```

--------------------------------

### Initialize BackgroundGeolocation with Basic Configuration

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

This snippet shows a minimal example of calling the `ready` method to initialize the BackgroundGeolocation SDK with essential configuration options like `distanceFilter`, `stopOnTerminate`, `logLevel`, and `debug`.

```javascript
BackgroundGeolocation.ready({
  distanceFilter: 10,
  stopOnTerminate: false,
  logLevel: BackgroundGeolocation.LOG_LEVEL_VERBOSE,
  debug: true
}, (state) => {
  console.log("- BackgroundGeolocation is ready: ", state);
});

```

--------------------------------

### Start and Stop Position Updates

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

Demonstrates how to use watchPosition to track location in the foreground and stopWatchPosition when the app is suspended to conserve battery.

```javascript
onResume() {
  // Start watching position while app in foreground.
  BackgroundGeolocation.watchPosition((location) => {
    console.log("[watchPosition] -", location);
  }, (errorCode) => {
    console.log("[watchPosition] ERROR -", errorCode);
  }, {
    interval: 1000
  })
}

onSuspend() {
  // Halt watching position when app goes to background.
  BackgroundGeolocation.stopWatchPosition();
}
```

--------------------------------

### startSchedule

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

Initiates the configured schedule. If a schedule was configured, this method will initiate that schedule. The plugin will automatically be started or stopped according to the configured schedule.

```APIDOC
## startSchedule

### Description
Initiate the configured schedule. If a schedule was configured, this method will initiate that schedule. The plugin will automatically be started or stopped according to the configured schedule. To halt scheduled tracking, use stopSchedule.

### Method
`startSchedule`

### Parameters
#### Success Callback
- **success** (function): Optional callback function that is executed when the operation is successful. It receives the current state as an argument.
  - **state** (State): The current state of the plugin.

#### Failure Callback
- **failure** (function): Optional callback function that is executed when the operation fails. It receives an error message as an argument.
  - **error** (string): An error message describing the failure.

#### Returns
- **Promise<State>** A promise that resolves with the current state of the plugin upon success, or rejects with an error message upon failure.
```

--------------------------------

### Configure Auto-Sync with Parameters

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/config.html

Enable immediate uploading of recorded locations to a configured URL. This example also includes custom parameters to be sent with each location.

```typescript
BackgroundGeolocation.ready({
  url: "http://my.server.com/locations",
  autoSync: true,
  params: {
    user_id: 1234
  }
})

```

--------------------------------

### Authorization Server Response Example (Complex)

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/authorization.html

An example of a complex JSON response structure from an authorization server, containing nested tokens and expiry information.

```json
{
  "token": {
    "access_token": "XXX.YYY.ZZZ",
    "expires_at": 3900
  },
  "refresh_token": "smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb"
}
```

--------------------------------

### Toggle between tracking modes

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/geofence.html

Allows toggling between standard location tracking (`start`) and geofences-only mode (`startGeofences`).

```APIDOC
## Toggling between tracking-modes start and startGeofences

### Description
The SDK can easily be toggled between tracking modes by executing the corresponding `start` or `startGeofences` methods.

### Methods
- **start**
- **startGeofences**

### Request Example
```javascript
// Listen to geofence events
BackgroundGeolocation.onGeofence(geofence => {
  console.log("[geofence] ", geofence);
  if (geofence.identifier == "DANGER_ZONE") {
    if (geofence.action == "ENTER") {
      // Entering the danger-zone, we want to aggressively track location.
      BackgroundGeolocation.start();
    } else if (geofence.action == "EXIT") {
      // Exiting the danger-zone, we resume geofences-only tracking.
      BackgroundGeolocation.startGeofences();
    }
  }
})

// Add a geofence.
BackgroundGeolocation.addGeofence({
  identifier: "DANGER_ZONE",
  radius: 1000,
  latitude: 45.51921926,
  longitude: -73.61678581,
  notifyOnEntry: true,
  notifyOnExit: true,
})

// Ready the plugin.
BackgroundGeolocation.ready({
  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10,
  url: "http://your.server.com/locations",
  autoSync: true
}, state => {
  BackgroundGeolocation.startGeofences();
})
```
```

--------------------------------

### Configure and Start Geofence-Only Mode

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/geofence.html

Configure the plugin for geofence-only monitoring using `geofenceModeHighAccuracy: true` for improved responsiveness. Then, engage this mode by calling `startGeofences` after `ready`.

```javascript
BackgroundGeolocation.onGeofence(geofence => {
  console.log("[geofence] ", geofence);
})

BackgroundGeolocation.ready({
  url: "http://your.server.com/geofences",
  autoSync: true,
  geofenceModeHighAccuracy: true   // <-- consumes more power; default is false.
}, state => {
  // engage geofences-only mode:
  BackgroundGeolocation.startGeofences();
})
```

--------------------------------

### Example SDK Log Output

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/logger.html

A sample of the log entries generated by the Background Geolocation SDK, showing service startup, location events, and HTTP requests.

```text
09-19 11:12:18.716 ╔═════════════════════════════════════════════
09-19 11:12:18.716 ║ BackgroundGeolocation Service started
09-19 11:12:18.716 ╠═════════════════════════════════════════════
09-19 11:12:18.723 [c.t.l.BackgroundGeolocationService d]
09-19 11:12:18.723   ✅  Started in foreground
09-19 11:12:18.737 [c.t.l.ActivityRecognitionService a]
09-19 11:12:18.737   🎾  Start activity updates: 10000
09-19 11:12:18.761 [c.t.l.BackgroundGeolocationService k]
09-19 11:12:18.761   🔴  Stop heartbeat
09-19 11:12:18.768 [c.t.l.BackgroundGeolocationService a]
09-19 11:12:18.768   🎾  Start heartbeat (60)
09-19 11:12:18.778 [c.t.l.BackgroundGeolocationService a]
09-19 11:12:18.778   🔵  setPace: null → false
09-19 11:12:18.781 [c.t.l.adapter.TSConfig c] ℹ️   Persist config
09-19 11:12:18.794 [c.t.locationmanager.util.b a]
09-19 11:12:18.794   ℹ️  LocationAuthorization: Permission granted
09-19 11:12:18.842 [c.t.l.http.HttpService flush]
09-19 11:12:18.842 ╔═════════════════════════════════════════════
09-19 11:12:18.842 ║ HTTP Service
09-19 11:12:18.842 ╠═════════════════════════════════════════════
09-19 11:12:19.000 [c.t.l.BackgroundGeolocationService onActivityRecognitionResult] still (100%)
09-19 11:12:21.314 [c.t.l.l.SingleLocationRequest$2 onLocationResult]
09-19 11:12:21.314 ╔═════════════════════════════════════════════
09-19 11:12:21.314 ║ SingleLocationRequest: 1
09-19 11:12:21.314 ╠═════════════════════════════════════════════
09-19 11:12:21.314 ╟─ 📍  Location[fused 45.519239,-73.617058 hAcc=15]999923706055 vAcc=2 sAcc=??? bAcc=???
09-19 11:12:21.327 [c.t.l.l.TSLocationManager onSingleLocationResult]
09-19 11:12:21.327   🔵  Acquired motionchange position, isMoving: false
09-19 11:12:21.342 [c.t.l.l.TSLocationManager a] 15.243
09-19 11:12:21.405 [c.t.locationmanager.data.a.c persist]
09-19 11:12:21.405   ✅  INSERT: bca5acc8-e358-4d8f-827f-b8c0d556b7bb
09-19 11:12:21.423 [c.t.l.http.HttpService flush]
09-19 11:12:21.423 ╔═════════════════════════════════════════════
09-19 11:12:21.423 ║ HTTP Service
09-19 11:12:21.423 ╠═════════════════════════════════════════════
09-19 11:12:21.446 [c.t.locationmanager.data.a.c first]
09-19 11:12:21.446   ✅  Locked 1 records
09-19 11:12:21.454 [c.t.l.http.HttpService a]
09-19 11:12:21.454   🔵  HTTP POST: bca5acc8-e358-4d8f-827f-b8c0d556b7bb
09-19 11:12:22.083 [c.t.l.http.HttpService$a onResponse]
09-19 11:12:22.083   🔵  Response: 200
09-19 11:12:22.100 [c.t.locationmanager.data.a.c destroy]
09-19 11:12:22.100   ✅  DESTROY: bca5acc8-e358-4d8f-827f-b8c0d556b7bb
09-19 11:12:55.226 [c.t.l.BackgroundGeolocationService onActivityRecognitionResult] still (100%)

```

--------------------------------

### Custom Location Template Example

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/config.html

Demonstrates how to use a custom template for rendering location data in HTTP requests, including basic and array formats.

```javascript
BackgroundGeolocation.ready({
  locationTemplate: '{"lat":<%= latitude %>,"lng":<%= longitude %>,"event":"<%= event %>",isMoving:<%= is_moving %>}'
});

// Or use a compact [Array] template!
BackgroundGeolocation.ready({
  locationTemplate: '[<%=latitude%>, <%=longitude%>, "<%=event%>", <%=is_moving%>]'
))
```

--------------------------------

### Initialize BackgroundGeolocation with Promise API

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

Initializes the BackgroundGeolocation plugin using the Promise API. This is the recommended way to start the service and configure its initial settings.

```javascript
// Traditional API still works:
BackgroundGeolocation.ready({"desiredAccuracy": 0, "distanceFilter": 50}).then(state => {
  console.log("- BackgroundGeolocation is ready: ", state);
}).catch(error => {
  console.log("- BackgroundGeolocation error: ", error);
});

```

--------------------------------

### Configure Initial Location Authorization Request

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/state.html

Sets the initial desired location authorization mode when the app launches. This example configures for 'WhenInUse'.

```javascript
onAppLaunch() {
  // Initially configure for 'WhenInUse'.
  BackgroundGeolocation.ready({
    locationAuthorizationRequest: 'WhenInUse',
    . 
    . 
    .
  });
}
```

--------------------------------

### Configure Background Geolocation

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/config.html

Use `BackgroundGeolocation.ready` to configure the SDK on startup or `BackgroundGeolocation.setConfig` for subsequent configuration changes. This example shows setting desired accuracy, distance filter, and server details.

```javascript
BackgroundGeolocation.ready({
  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10,
  stopOnTerminate: false,
  startOnBoot: true,
  url: "http://my.server.com",
  params: {
    "user_id": 123
  },
  headers: {
    "my-auth-token":"secret-key"
  }
}).then((state) => {
  console.log("[ready] BackgroundGeolocation is configured and ready to use");

  BackgroundGeolocation.start();
})

// Or with #setConfig
BackgroundGeolocation.setConfig({
  extras: {route_id: 1234},
  url: "https://my.new.server.com"
})
```

--------------------------------

### RPC: Stop Command Example

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/httpevent.html

Instruct the SDK to stop background location tracking by returning a JSON response with the 'stop' command.

```json
{
  "background_geolocation": [
    ["stop"]
  ]
}
```

--------------------------------

### Configure Authorization with Refresh Headers Example

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/authorization.html

Demonstrates configuring the authorization object with specific refresh headers, including an empty object to disable default headers. This is useful for custom authentication flows.

```javascript
BackgroundGeolocation.ready({
  authorization: {
    accessToken: "XXX.YYY.ZZZ",
    refreshUrl: "https://auth.domain.com/tokens",
    refreshToken: "smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb",
    refreshPayload: {
      "my_refresh_token": "{refreshToken}", // <-- replaced with configured refreshToken above.
      "grant_type": "refresh_token",        // <-- arbitrary fields required by your auth server
      "foo": "another arbitrary field"
    },
    refreshHeaders: {}  // <-- Empty {} to provide no refreshHeaders.
  )
));

```

--------------------------------

### Toggle Between Tracking Modes

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/geofence.html

Dynamically switch between standard location tracking (`start`) and geofence-only monitoring (`startGeofences`) based on geofence events. This allows for power-efficient monitoring until a specific geofence is entered.

```javascript
// Listen to geofence events
BackgroundGeolocation.onGeofence(geofence => {
  console.log("[geofence] ", geofence);
  if (geofence.identifier == "DANGER_ZONE") {
    if (geofence.action == "ENTER") {
      // Entering the danger-zone, we want to aggressively track location.
      BackgroundGeolocation.start();
    } else if (geofence.action == "EXIT") {
      // Exiting the danger-zone, we resume geofences-only tracking.
      BackgroundGeolocation.startGeofences();
    }
  }
})

// Add a geofence.
BackgroundGeolocation.addGeofence({
  identifier: "DANGER_ZONE",
  radius: 1000,
  latitude: 45.51921926,
  longitude: -73.61678581,
  notifyOnEntry: true,
  notifyOnExit: true,
})

// Ready the plugin.
BackgroundGeolocation.ready({
  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10,
  url: "http://your.server.com/locations",
  autoSync: true
}, state => {
  BackgroundGeolocation.startGeofences();
})
```

--------------------------------

### Watch Position Example

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/watchpositionrequest.html

Demonstrates how to use BackgroundGeolocation.watchPosition to receive location updates and handle errors. Configures interval, desired accuracy, persistence, extras, and timeout.

```javascript
BackgroundGeolocation.watchPosition((location) => {
  console.log("[watchPosition] -", location);
}, (errorCode) => {
  console.log("[watchPosition] ERROR -", errorCode);
}, {
  interval: 1000,
  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
  persist: true,
  extras: {foo: "bar"},
  timeout: 60000
});

```

--------------------------------

### Inserting a Debug Log Message

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/logger.html

Provides a direct example of how to use the `debug` method to insert a message into the SDK's log database.

```javascript
BackgroundGeolocation.logger.debug("This is a debug message");

```

--------------------------------

### Configure Foreground Service Notification

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/notification.html

Set up the initial title and text for the persistent notification when starting the foreground service. Use `setConfig` to update the notification dynamically.

```javascript
BackgroundGeolocation.ready({
  notification: {
    title: "The Title",
    text: "The Text"
  }
})
. 
. 
. 
// To update the notification in real-time, use #setConfig
// You need only provide *changed* parameters --  initially configured
// parameters will remain unchanged.
BackgroundGeolocation.setConfig({
  notification: {
    title: "The New Title"
  }
})
```

--------------------------------

### Configure Daily Tracking Schedule

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/state.html

Set up an automated schedule for the plugin to start and stop tracking. Times are in 24h format, and days correspond to Locale.US (Sunday=1, Saturday=7).

```javascript
BackgroundGeolocation.ready({
  // ... other config
  schedule: [
    "1 17:30-21:00",    // Sunday: 5:30pm-9:00pm
    "2-6 9:00-17:00",   // Mon-Fri: 9:00am to 5:00pm
    "2,4,6 20:00-00:00",// Mon, Web, Fri: 8pm to midnight (next day)
    "7 10:00-19:00"     // Sat: 10am-7pm
  ]
}).then((state) => {
  // Start the Scheduler
  BackgroundGeolocation.startSchedule();
});

// Listen to #onSchedule events:
BackgroundGeolocation.onSchedule((state) => {
  let enabled = state.enabled;
  console.log("[onSchedule] - enabled? ", enabled);
});

// Later when you want to stop the Scheduler (eg: user logout)
BackgroundGeolocation.stopSchedule();
// You must explicitly stop tracking if currently enabled
BackgroundGeolocation.stop();

// Or modify the schedule with usual #setConfig method
BackgroundGeolocation.setConfig({
  schedule: [
    "1-7 9:00-10:00",
    "1-7 11:00-12:00",
    "1-7 13:00-14:00",
    "1-7 15:00-16:00",
    "1-7 17:00-18:00",
    "2,4,6 19:00-22:00"
  ]
});

```

--------------------------------

### Handle Multipart Log Upload on Server

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/logger.html

Example Node.js server endpoint to handle multipart file uploads from the SDK. It logs the request body and files received.

```javascript
app.post("/log", async function(req, res) {
  console.log("[body]: ", req.body);
  console.log("[files]: ", req.files);
  res.status(200).send();
});
```

--------------------------------

### Configure SDK with Access Token

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/transistorauthorizationtoken.html

Shows how to set the authorization accessToken when configuring the SDK using the `ready` method.

```javascript
BackgroundGeolocation.ready({
 authorization: {
 accessToken:
 }
});

```

--------------------------------

### Schedule Tracking with Literal Dates

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/config.html

Configures the schedule using literal dates. Supports a single literal start date or two literal dates for both start and stop.

```javascript
BackgroundGeolocation.ready({
  schedule: [
    "2018-01-01 09:00-17:00"
  ]
});
```

```javascript
schedule: [
    "2018-01-01-09:00 2019-01-01-17:00"  // <-- track for 1 year
  ]
```

--------------------------------

### show

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/devicesettings.html

This method is designed to be executed from a showPowerManager or showIgnoreBatteryOptimizations callback. It attempts to show a device-specific settings screen.

```APIDOC
## show

### Description
This method is designed to be executed from a showPowerManager or showIgnoreBatteryOptimizations callback.

### Method
`show(request: DeviceSettingsRequest): Promise<boolean>`

### Parameters
#### request: DeviceSettingsRequest

### Returns
Promise<boolean>
```

--------------------------------

### Configure Authorization and Ready

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/interfaces/authorization.html

Sets up an authorization event listener and configures the SDK with authorization details, including token refresh settings. Use this to automatically manage authentication tokens for server requests.

```javascript
let myToken = this.getMyAuthorizationToken();

BackgroundGeolocation.onAuthorization((event) => {
  if (event.success) {
    console.log("[authorization] ERROR: ", event.error);
  } else {
    console.log("[authorization] SUCCESS: ", event.response);
  }
});

BackgroundGeolocation.ready({
  url: "https://app.your.server.com/users/locations",
  autoSync: true,
  authorization: {
    strategy: "JWT",
    accessToken: myToken.accessToken,
    refreshToken: myToken.refreshToken,
    refreshUrl: "https://auth.your.server.com/tokens",
    refreshPayload: {
      the_refresh_token_field_name: "{refreshToken}"
    },
    expires: myToken.expiresAt
  }
});

```

--------------------------------

### Start Watching Position Updates

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

Starts a stream of continuous location-updates. This is primarily designed for foreground use only, for fast-updates of the user's current position on the map. The SDK's primary philosophy of operation does not require watchPosition.

```javascript
onResume() {
  // Start watching position while app in foreground.
  BackgroundGeolocation.watchPosition((location) => {
    console.log("[watchPosition] -", location);
  }, (errorCode) => {
    console.log("[watchPosition] ERROR -", errorCode);
  }, {
   interval: 1000
  })
}
```

--------------------------------

### ready

Source: https://transistorsoft.github.io/react-native-background-geolocation/4.x/classes/backgroundgeolocation.html

Signal to the plugin that your app is launched and ready, proving the default Config. The supplied Config will be applied **only at first install** of your app — for every launch thereafter, the plugin will automatically load its last-known configuration from persistent storage. The plugin always remembers the configuration you apply to it.

```APIDOC
### Static ready
  * ready(config: Config, success?: (state: State) => void, failure?: (error: string) => void): Promise<State>


  * Signal to the plugin that your app is launched and ready, proving the default Config.
The supplied Config will be applied **only at first install** of your app — for every launch thereafter, the plugin will automatically load its last-known configuration from persistent storage. The plugin always remembers the configuration you apply to it. 

example
    ```
BackgroundGeolocation.ready({
  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10,
  stopOnTerminate: false,
  startOnBoot: true,
  url: "http://your.server.com",
  headers: {
   "my-auth-token": "secret-token"
  }
}).then((state) => {
 console.log("[ready] success", state);
});

```

### ⚠️ Warning: You must call **`.ready(confg)`****once** and **only** once, each time your app is launched.
    * Do not hide the call to `#ready` within a view which is loaded only by clicking a UI action. This is particularly important for iOS in the case where the OS relaunches your app in the background when the device is detected to be moving. If you don't ensure that `#ready` is called in this case, tracking will not resume.
### The reset method.
If you wish, you can use the reset method to reset all Config options to documented default-values (with optional overrides):
```
Tokens:
Raw