Config¶

export interface Config {

Root configuration object passed to BackgroundGeolocation.ready and BackgroundGeolocation.setConfig.

Config groups all SDK options into typed sub-interfaces. Each key maps to a dedicated configuration area — set only the keys relevant to your use case.

Contents¶

Overview
Examples

Overview¶

Key	Type	Description
`geolocation`	GeoConfig	Accuracy, sampling, elasticity, stop-detection, permissions, and geofencing.
`activity`	ActivityConfig	Motion recognition, stop-detection triggers, and motion-trigger delay.
`http`	HttpConfig	Upload URL, sync cadence, batching, headers, and params.
`persistence`	PersistenceConfig	SQLite storage, TTL, record limits, and custom extras.
`app`	AppConfig	App lifecycle — background operation, boot behaviour, headless mode, and foreground notification.
`logger`	LoggerConfig	Debug logging, log level, and log retention.
`authorization`	AuthorizationConfig	JWT and SAS token management with automatic refresh.

The SDK persists its configuration across app launches. Call BackgroundGeolocation.ready once at startup — subsequent launches load the persisted config automatically. Use BackgroundGeolocation.setConfig to update individual keys at runtime without restarting.

Examples¶

const state = await BackgroundGeolocation.ready({
  geolocation: {
    desiredAccuracy: DesiredAccuracy.High,
    distanceFilter: 20,
  },
  http: {
    url: 'https://my.server.com/api/locations',
    autoSync: true,
  },
  app: {
    stopOnTerminate: false,
    startOnBoot: true,
  },
});

import BackgroundGeolocation, {
  Config,
  GeoConfig,
  ActivityConfig,
  HttpConfig,
  PersistenceConfig,
  DesiredAccuracy,
  PersistMode,
  LogLevel,
  AppConfig,
  LoggerConfig,
  State
} from 'react-native-background-geolocation';

const config: Config = {
  geolocation: {
    desiredAccuracy: DesiredAccuracy.High,
    distanceFilter: 20,
    stopTimeout: 5,
    stationaryRadius: 150,
  },
  activity: {
    disableStopDetection: false,
    motionTriggerDelay: 30000,
  },
  http: {
    url: 'https://my.server.com/api/locations',
    method: 'POST',
    autoSync: true,
    headers: { Authorization: 'Bearer secret-token' },
    params: { user_id: 123 },
  },
  persistence: {
    persistMode: PersistMode.All,
    maxDaysToPersist: 14,
    extras: { appVersion: '1.0.0' },
  },
  app: {
    stopOnTerminate: false,
    startOnBoot: true,
    enableHeadless: true,
  },
  logger: {
    debug: true,
    logLevel: LogLevel.Verbose,
    logMaxDays: 3,
  },
};

const state: State = await BackgroundGeolocation.ready(config);
if (!state.enabled) {
  await BackgroundGeolocation.start();
}

// Update a subset of config at runtime.
await BackgroundGeolocation.setConfig({
  http: { headers: { Authorization: 'Bearer new-token' } },
  logger: { logLevel: LogLevel.Info },
});

Minimal configuration¶

const state = await BackgroundGeolocation.ready({
  geolocation: {
    desiredAccuracy: DesiredAccuracy.High,
    distanceFilter: 20,
  },
  http: {
    url: 'https://my.server.com/api/locations',
    autoSync: true,
  },
  app: {
    stopOnTerminate: false,
    startOnBoot: true,
  },
});

Full configuration¶

import BackgroundGeolocation, {
  Config,
  GeoConfig,
  ActivityConfig,
  HttpConfig,
  PersistenceConfig,
  DesiredAccuracy,
  PersistMode,
  LogLevel,
  AppConfig,
  LoggerConfig,
  State
} from '{{pluginName}}';

const config: Config = {
  geolocation: {
    desiredAccuracy: DesiredAccuracy.High,
    distanceFilter: 20,
    stopTimeout: 5,
    stationaryRadius: 150,
  },
  activity: {
    disableStopDetection: false,
    motionTriggerDelay: 30000,
  },
  http: {
    url: 'https://my.server.com/api/locations',
    method: 'POST',
    autoSync: true,
    headers: { Authorization: 'Bearer secret-token' },
    params: { user_id: 123 },
  },
  persistence: {
    persistMode: PersistMode.All,
    maxDaysToPersist: 14,
    extras: { appVersion: '1.0.0' },
  },
  app: {
    stopOnTerminate: false,
    startOnBoot: true,
    enableHeadless: true,
  },
  logger: {
    debug: true,
    logLevel: LogLevel.Verbose,
    logMaxDays: 3,
  },
};

const state: State = await BackgroundGeolocation.ready(config);
if (!state.enabled) {
  await BackgroundGeolocation.start();
}

// Update a subset of config at runtime.
await BackgroundGeolocation.setConfig({
  http: { headers: { Authorization: 'Bearer new-token' } },
  logger: { logLevel: LogLevel.Info },
});

Members¶

activity¶

activity?:ActivityConfig;

Motion recognition, stop-detection triggers, and motion-trigger delay. Access via BGGeo.instance.config.activity. See ActivityConfig.

app¶

app?:AppConfig;

App lifecycle, background operation, boot behaviour, headless mode, and foreground notification. Access via BGGeo.instance.app. See AppConfig.

authorization¶

authorization?:AuthorizationConfig;

JWT and SAS token management with automatic refresh. Access via BGGeo.instance.authorization. See AuthorizationConfig.

geolocation¶

geolocation?:GeoConfig;

Accuracy, sampling, elasticity, stop-detection, permissions, and geofencing. Access via BGGeo.instance.config.geolocation. See GeoConfig.

http¶

http?:HttpConfig;

Upload URL, HTTP method, sync cadence, batching, headers, and params. Access via BGGeo.instance.config.http. See HttpConfig.

logger¶

logger?:LoggerConfig;

Debug logging, log level, and log retention. Access via BGGeo.instance.config.logger. See LoggerConfig.

persistence¶

persistence?:PersistenceConfig;

SQLite storage, TTL, record limits, and custom extras. Access via BGGeo.instance.config.persistence. See PersistenceConfig.

reset¶

reset?: boolean;

Controls whether the SDK resets to factory defaults before applying this configuration. Defaults to true.

When true (the default), every call to BackgroundGeolocation.ready applies the supplied Config on top of fresh defaults. When false, the SDK applies the supplied Config only on the first install. On subsequent launches it ignores the Config argument entirely — the only way to change settings is via BackgroundGeolocation.setConfig.

Warning

During development, always leave reset: true (or omit it). Setting reset: false causes the SDK to ignore your Config after the first launch, so configuration changes made between development builds will not take effect.

transistorAuthorizationToken¶

transistorAuthorizationToken?:TransistorAuthorizationToken;

Convenience option that automatically configures the SDK to upload locations to the Transistor Software demo server at tracker.transistorsoft.com, or a local instance of background-geolocation-console.

Setting this option automatically sets HttpConfig.url and the required AuthorizationConfig values. See TransistorAuthorizationService for how to obtain a token.

const token = await BackgroundGeolocation.findOrCreateTransistorAuthorizationToken(
  "my-company-name",
  "my-username"
);

BackgroundGeolocation.ready({
  transistorAuthorizationToken: token
});

// Base url to Transistor Demo Server.
const url = "http://tracker.transistorsoft.com";

// Register for an authorization token from server.
const token = await
  BackgroundGeolocation.findOrCreateTransistorAuthorizationToken("my-company-name", "my-username");

BackgroundGeolocation.ready({
  url: url + "/api/locations",
  authorization: {
    strategy: "JWT",
    accessToken: token.accessToken,
    refreshToken: token.refreshToken,
    refreshUrl: url + "/v2/refresh_token",
    refreshPayload: {
      refresh_token: "{refreshToken}"
    },
    expires: token.expires
  }
});