react-native-background-geolocation@5.0.0-beta.1
    Preparing search index...

    Interface HttpConfig

    HTTP / Networking Configuration

    The HttpConfig group controls how recorded locations are uploaded to your server. It defines the endpoint, HTTP verb, headers, params, batching behavior, and request timeouts.

    These options apply to all automatic syncs as well as manual syncs triggered by the app.

    BackgroundGeolocation.ready({
      http: {
        url: "https://example.com/locations",
        autoSync: true,
        params: { user_id: 1234 }
      }
    });

    Overview

    The SDK persistently stores each recorded location in its internal SQLite database before attempting to upload it. The HTTP Service continuously consumes this queue of stored records in the background. For each record:

    1. A record-level lock is acquired to prevent duplicate uploads.
    2. The record is serialized into an HTTP request and posted to url.
    3. A 2xx response marks the record as delivered and it is deleted.
    4. Failed or timed-out uploads remain locked until released for retry.

    The uploader operates automatically across:

    • background execution
    • app termination
    • device reboot

    When connectivity returns, it resumes processing any remaining records.

    Area Keys Notes
    Destination url, method method defaults to POST.
    Payload rootProperty, params, headers Controls JSON body and headers.
    Sync cadence autoSync, autoSyncThreshold, batchSync, maxBatchSize Immediate vs batched uploads.
    Network policy disableAutoSyncOnCellular, timeout Conserve bandwidth and battery.

    How uploads work

    1. Each location is written to SQLite.
    2. Pending records are locked for upload.
    3. Locked records are sent to url.
    4. On success (2xx), the record is deleted.
    5. On failure, the record is unlocked and retried later.

    The SQLite buffer

    The storage acts as a rolling buffer and is normally empty. Records disappear when:

    Inspect queue size using BackgroundGeolocation.getCount or fetch with BackgroundGeolocation.getLocations.

    Payload composition

    • Body: JSON. If batchSync is true, an array of records is sent.
      If rootProperty is set, payload becomes:

      { "<rootProperty>": [...] }

    • Headers: Combined from headers plus authorization if configured.

    • Params: Added to every payload at the root or under rootProperty.

    Uploads use application/json; authorization refresh requests use application/x-www-form-urlencoded.

    Sync strategy

    • autoSync: upload after each record
    • autoSyncThreshold: wait for N records
    • batchSync: upload several records in one request
    • maxBatchSize: max records per batch
    • timeout: maximum HTTP duration
    • disableAutoSyncOnCellular: defer uploads until Wi-Fi

    Error handling & retries

    On non-2xx or network failure, records remain in queue and are retried when:

    Or manually:

    await BackgroundGeolocation.sync();

    HTTP Logging

    Logs provide insight into HTTP behavior:

    📍 Location
✅ INSERT: record stored
🔒 Locked 1 records
🔵 HTTP POST
🔵 Response: 200
✅ DESTROY
    # Entry Meaning
    1 📍 Location Raw location recorded
    2 INSERT Persisted to SQLite
    3 Locked Marked for upload
    4 HTTP POST/PUT Attempted upload
    5 Response Server status
    6 DESTROY / UNLOCK Success / failed retry

    Remote control via HTTP response (RPC)

    Your server may instruct the SDK to execute commands by returning JSON containing a background_geolocation payload.

    Multiple commands

    {
      "background_geolocation": [
        ["setConfig", { "geolocation": { "distanceFilter": 25 } }],
        ["start"]
      ]
    }

    Single command

    { "background_geolocation": ["stop"] }

    Supported remote commands

    Command Arguments Effect
    "start" — BackgroundGeolocation.start
    "stop" — BackgroundGeolocation.stop
    "startGeofences" — BackgroundGeolocation.startGeofences
    "changePace" boolean BackgroundGeolocation.changePace
    "setConfig" {Config} BackgroundGeolocation.setConfig
    "addGeofence" {Geofence} BackgroundGeolocation.addGeofence
    "addGeofences" [{Geofence}, ...] BackgroundGeolocation.addGeofences
    "removeGeofence" identifier:string BackgroundGeolocation.removeGeofence
    "removeGeofences" list or none remove all or some
    "uploadLog" url:string upload plugin log
    "destroyLog" — delete plugin log

    Examples

    Simple upload:

    BackgroundGeolocation.ready({
      http: {
        url: "https://api.example.com/locations",
        method: "POST",
        autoSync: true,
        headers: { Authorization: "Bearer secret" },
        params: { device_id: "abc-123" }
      }
    });

    Batched uploads:

    BackgroundGeolocation.ready({
      http: {
        url: "https://api.example.com/locations/bulk",
        autoSync: true,
        batchSync: true,
        maxBatchSize: 25,
        autoSyncThreshold: 10,
        rootProperty: "locations"
      }
    });

    Conserve cellular data:

    BackgroundGeolocation.ready({
      http: {
        url: "https://api.example.com/locations",
        autoSync: true,
        disableAutoSyncOnCellular: true
      }
    });

    Manual sync:

    await BackgroundGeolocation.setConfig({
      http: { url: "https://api.example.com", autoSync: false }
    });

    await BackgroundGeolocation.sync();

    Migration from legacy flat Config

    Old:

    BackgroundGeolocation.ready({
      url: "https://api.example.com",
      autoSync: true,
      headers: { Authorization: "Bearer ..." }
    });

    New (compound):

    BackgroundGeolocation.ready({
      http: {
        url: "https://api.example.com",
        autoSync: true,
        headers: { Authorization: "Bearer ..." }
      }
    });

    Legacy keys remain available but are @deprecated and will be removed in a future major release.

    interface HttpConfig {
        url?: string;
        headers?: Record<string, string>;
        params?: Record<string, any>;
        method?: HttpMethod;
        autoSync?: boolean;
        autoSyncThreshold?: number;
        disableAutoSyncOnCellular?: boolean;
        batchSync?: boolean;
        maxBatchSize?: number;
        rootProperty?: string;
        timeout?: number;
    }
    Index

    Properties

    url? headers? params? method? autoSync? autoSyncThreshold? disableAutoSyncOnCellular? batchSync? maxBatchSize? rootProperty? timeout?

    Properties

    url?: string

    Server URL where you want the SDK to post recorded locations.

    Both the iOS and Android native code host their own robust HTTP service which can automatically upload recorded locations to your server. This is particularly important on Android when running headless with AppConfig.stopOnTerminate set to false, since only the plugin's background service continues running in that state.

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

    BackgroundGeolocation.ready({
      http: {
        url: "https://my-server.com/locations",
        params: {
          user_id: 1234
        },
        headers: {
          Authorization: "Basic my-secret-key"
        },
        autoSync: true,
        method: "POST"
      },
      app: {
        stopOnTerminate: false
      }
    });

    Warning: It is highly recommended to let the SDK manage uploads to your server, especially on Android when AppConfig.stopOnTerminate is false. In that mode your application component will terminate—only the native Android background service continues operating, recording locations and posting them to your server. The SDK’s HTTP service automatically retries on failures and is more reliable for background delivery than ad-hoc HTTP requests from your own code.

    See the HTTP guide under HttpConfig for full examples, error handling, and payload structure.

    headers?: Record<string, string>

    Optional HTTP headers applied to every outbound upload request.

    These headers are merged with the SDK’s automatically applied headers (such as "content-type": "application/json"). When using authorization, the SDK also injects an Authorization header as needed.

    BackgroundGeolocation.ready({
      http: {
        url: "https://my.server.com",
        headers: {
          Authorization: "Bearer <a secret key>",
          "X-FOO": "BAR"
        }
      }
    });

    Observing incoming requests at your server:

    POST /locations
{
  "host": "tracker.transistorsoft.com",
  "content-type": "application/json",
  "content-length": "456",
  ...
  "authorization": "Bearer <a secret key>",
  "X-FOO": "BAR"
}

    Note:
    The SDK automatically applies several required headers, including:

    See also: the HTTP Guide under HttpConfig.

    params?: Record<string, any>

    Optional HTTP params appended to the JSON body of each outbound upload request.

    These key/value pairs are merged into the payload sent to your server (either at the root level or under rootProperty, if configured).

    BackgroundGeolocation.ready({
      http: {
        url: "https://my-server.com/locations",
        params: {
          user_id: 1234,
          device_id: "abc123"
        }
      }
    });

    Example request body received by your server:

    {
      "location": {
        "coords": {
          "latitude": 45.51927,
          "longitude": -73.61650
          // ...
        }
      },
      "user_id": 1234,      // <-- params merged into the payload
      "device_id": "abc123"
    }

    See also: the HTTP Guide under HttpConfig.

    method?: HttpMethod

    The HTTP method used when uploading locations to your configured url.

    Defaults to POST.

    Valid values: POST, PUT, OPTIONS.

    BackgroundGeolocation.ready({
      http: {
        url: "https://my-server.com/locations",
        method: "PUT"
      }
    });
    autoSync?: boolean

    Immediately upload each recorded location to your configured url.

    Defaults to true.

    When autoSync is enabled and a url is provided, the SDK will attempt to upload each location as soon as it is recorded.

    If you set autoSync: false, you must manually call BackgroundGeolocation.sync to initiate uploads.
    Regardless of autoSync, all recorded locations are persisted in the SDK’s internal SQLite database until successfully delivered.

    Note: The queue continues to grow until you call BackgroundGeolocation.sync or until uploads succeed.

    See also

    autoSyncThreshold?: number

    The minimum number of persisted records the plugin must accumulate before triggering an automatic upload via autoSync.

    Defaults to 0 (no threshold).

    When set to a value greater than 0, the SDK will wait until at least that many locations are recorded before uploading to your configured url.

    Using autoSyncThreshold together with batchSync can significantly reduce battery consumption, since batching minimizes the number of HTTP requests (which cost far more power than GPS work).

    ⚠️ Warning: Ignored during onMotionChange

    If you've configured autoSyncThreshold, it will be ignored during BackgroundGeolocation.onMotionChange transitions:

    • Entering the moving state:
      The device may have been dormant for a long time; the SDK eagerly uploads queued locations immediately.

    • Entering the stationary state:
      The device may soon become dormant; the SDK eagerly uploads all queued locations before going idle.

    See also

    disableAutoSyncOnCellular?: boolean

    Disable autoSync when the device is connected over cellular data.

    Defaults to false.

    When set to true, automatic HTTP uploads will occur only when on Wi-Fi.

    This is useful for conserving mobile data usage, particularly when large batches of locations may accumulate while offline.

    ⚠️ Warning: This option is ignored when manually invoking BackgroundGeolocation.sync. Manual syncs always proceed regardless of connection type.

    See also

    batchSync?: boolean

    Upload multiple locations to your url in a single HTTP request.

    Defaults to false.
    When set to true, the SDK will bundle all currently queued locations in the native SQLite database and upload them together in one HTTP request.

    When batchSync is false, the HTTP service performs one request per location, which can increase battery and network usage.

    Batching is often used together with autoSyncThreshold to reduce upload frequency and conserve power.

    See also

    maxBatchSize?: number

    Controls the number of records attached to each batched HTTP request.

    Defaults to -1 (no maximum).

    When using batchSync with url configured, this option limits how many queued location records may be included in a single HTTP request.

    If the number of queued records exceeds maxBatchSize, the SDK will generate multiple HTTP requests until the queue is fully drained.

    This prevents extremely large request bodies when the device has been offline for long periods (where megabytes of location data may accumulate).

    See also

    rootProperty?: string

    The root property of the JSON object where location data will be placed.

    When set, outgoing HTTP payloads will wrap the serialized location record(s) under the specified key.

    BackgroundGeolocation.ready({
      http: {
        rootProperty: "myData",
        url: "https://my.server.com",
      }
    });

    Produces payloads shaped like:

    {
      "myData": {
        "coords": {
          "latitude": 23.232323,
          "longitude": 37.373737
        }
      }
    }

    If you specify "." (dot), the SDK places the data directly in the root of the JSON body:

    {
      "coords": {
        "latitude": 23.232323,
        "longitude": 37.373737
      }
    }

    Note: See the HTTP Guide at HttpConfig for detailed payload examples and composition rules.

    See also

    timeout?: number

    HTTP request timeout in milliseconds.

    When an HTTP request exceeds this timeout, the SDK fires BackgroundGeolocation.onHttp with a failure event.

    Defaults to 60000 ms.

    BackgroundGeolocation.onHttp((response) => {
      if (!response.success) {
        console.log("[onHttp] FAILURE:", response);
      }
    });

    BackgroundGeolocation.ready({
      http: {
        url: "https://my-server.com/locations",
        timeout: 3000   // 3-second timeout
      }
    });

    Settings

    Member Visibility

    On This Page

    Properties