Interface PersistenceConfig

Persistence / Storage Configuration

The PersistenceConfig group controls how the SDK stores, orders, and purges records in its on-device SQLite database. The database acts as a durable buffer between data producers (locations, geofences) and consumers (your app code and the HTTP service).

BackgroundGeolocation.ready({
  persistence: {
    maxDaysToPersist: 3,
    maxRecordsToPersist: 1000,
    extras: {
      'user_id': 123,
      'appVersion': '1.2.3'
    },
    persistMode: PersistMode.All
  }
});
Copy

The SDK prefers an empty database. Each new Location (and geofence event) is written to SQLite immediately, then consumed (and typically deleted) by downstream services such as the HTTP uploader. When a record is successfully processed (e.g., posted to your server), it is removed to keep the buffer small and responsive.

Configure PersistenceConfig via Config.persistence.

What gets stored?

• Locations recorded by the tracker
• Geofence events (enter / exit / dwell)
• Extras merged at write time via extras

When are records deleted?

A record is deleted when any of the following occur:

• Your server returns a 20x for the HTTP upload (see HttpConfig)
• You call BackgroundGeolocation.destroyLocations
• maxDaysToPersist elapses (rolling TTL purge)
• maxRecordsToPersist would be exceeded
  (oldest records are dropped)

Inspect pending records using:

• BackgroundGeolocation.getCount
• BackgroundGeolocation.getLocations

Ordering

The order in which records are selected for upload or consumption is controlled by locationsOrderDirection:

• "ASC" → oldest first (default)
• "DESC" → newest first

JSON templating

Customize the JSON structure of uploaded records:

• locationTemplate
• geofenceTemplate

Templates receive the full record context and can reshape, rename, or nest fields to match backend requirements (see also HttpConfig.rootProperty).

Extras

extras is a free-form key/value map merged into every record when written. Ideal for static context such as user_id, route_id, appVersion, etc.

Persist mode

Control what is written to SQLite with PersistMode:

• PersistMode.All — persist locations + geofences
• PersistMode.Location — persist locations only
• PersistMode.Geofence — persist geofences only
• PersistMode.None — do not persist (live callbacks still fire)

Even with PersistMode.None, HTTP uploads can still occur if triggered directly. Persistence controls the buffer, not the upload.

Example

const location = await bg.BackgroundGeolocation.getCurrentPosition({
  persist: true,
  extras: {"get_current_position": true},
  samples: 3,
});
Copy

In this case, the fetched location is persisted (because persist: true, overriding persistMode), then uploaded immediately if HttpConfig.autoSync is enabled.

ProviderChange Records

Disable storage of diagnostic “provider change” records (GPS toggled, settings changed, etc.) with disableProviderChangeRecord to keep the database lean.

Examples

Configure persistence behavior

const config = {
  persistence: {
    maxDaysToPersist: 14,
    maxRecordsToPersist: 5000,
    locationsOrderDirection: 'ASC',
    persistMode: PersistMode.All,
    extras: {'user_id': 123, 'appVersion': '1.2.3'},
  },
  http: {
    url: 'https://example.com/locations',
    autoSync: true,
  }
});
const state = await BackgroundGeolocation.ready(config);
Copy

Inspect and purge the database

final pending = await BackgroundGeolocation.getCount();
console.log('Pending records: $pending');

// Purge all records
final ok = await bg.BackgroundGeolocation.destroyLocations();
console.log('Destroyed all records? $ok');
Copy

Custom JSON templates

const config = {
  persistence: {
    locationTemplate: '''
    {
      "lat": <%= latitude %>,
      "lng": <%= longitude %>,
      "ts": "<%= timestamp %>",
      "meta": <%= JSON.stringify(extras) %>
    }
    ''',
    geofenceTemplate: '''
    {
      "id": "<%= identifier %>",
      "action": "<%= action %>",
      "ts": "<%= timestamp %>"
    }
    ''',
  },
};
Copy

Migration from legacy flat Config

// Legacy
{
  maxDaysToPersist: 14,
  maxRecordsToPersist: 5000,
  locationsOrderDirection: 'ASC',
  locationTemplate: '{...}',
  geofenceTemplate: '{...}',
  persistMode: Config.PERSIST_MODE_ALL,
  extras: {'user_id': 123},
  disableProviderChangeRecord: true,
};
Copy

Now grouped under PersistenceConfig:

{
  persistence: {
    maxDaysToPersist: 14,
    maxRecordsToPersist: 5000,
    locationsOrderDirection: 'ASC',
    locationTemplate: '{...}',
    geofenceTemplate: '{...}',
    persistMode: PersistMode.all,
    extras: {'user_id': 123},
    disableProviderChangeRecord: true,
  },
};
Copy

Legacy keys remain but are marked @deprecated. Prefer the compound form going forward.