Methods

import LongPing from 'react-native-long-ping';

Every method returns a promise. A rejection carries a code from Error codes. Methods work whether or not tracking is running unless noted.

Setup

configure

configure(config: Config): Promise<State>

Replaces the whole config with the defaults plus config, validates it, saves it on the device and applies it live. Never starts, stops or prompts, so it is safe to call on every launch. Rejects INVALID_CONFIG with the offending key in the message. See Config.

setConfig

setConfig(config: Config): Promise<State>

Deep-merges config into the current config (objects merge, arrays and scalars replace), validates, saves and applies it. Use it to change one or two settings at runtime:

await LongPing.setConfig({ movingIntervalSec: 5 });

Tracking

start

start(): Promise<State>

Checks permission and location services, saves enabled = true, starts tracking and records an immediate motionchange fix in the moving state. Never shows a permission dialog.

Rejects PERMISSION_DENIED or LOCATION_SERVICES_OFF; nothing is saved in that case. When tracking is already enabled it only makes sure tracking runs (no forced moving state, no extra motionchange), so calling it on every launch is safe.

stop

stop(): Promise<State>

Saves enabled = false and stops location updates (and, on Android, the foreground service). The queue is kept and keeps uploading until it is empty.

getState

getState(): Promise<State>

Resolves the current State: enabled, moving, last location, queue count, whether upload auth is needed, and the full config.

changePace

changePace(isMoving: boolean): Promise<State>

Forces moving (true) or parked (false) now and records a motionchange fix. false parks at the last fix; normal stop detection takes over from there. Rejects NOT_ENABLED when tracking is stopped.

changePace(false) while the vehicle is still moving only lasts until the next moving fix: stop detection sees the speed (or the distance from the parked position) and switches back to moving. That is by design, so a mistaken “parked” can never silence a moving vehicle.

A motion change from start(), changePace() or leaving the parked region waits up to 30 s for an accurate fix, then records the best one seen.

getCurrentPosition

getCurrentPosition(options?: CurrentPositionOptions): Promise<Location>

Takes one fix. Works while tracking is stopped (it still needs location permission).

Option	Type	Default
`timeoutSec`	`number`	`30`	How long to wait for a fix.
`maximumAgeSec`	`number`	`0`	Accept a cached fix this young.
`accuracy`	`'high' \| 'balanced' \| 'low'`	config `accuracy`
`persist`	`boolean`	`false`	Record and upload the fix, with event `current`.
`extras`	`object`	`{}`	Merged over `http.extras` for this record.

On timeout it resolves the best fix seen in the window, if any; otherwise the last known fix if it is younger than 10 minutes; otherwise it rejects TIMEOUT. On iOS it resolves early once accuracy reaches 20 / 100 / 1000 m (high / balanced / low); on Android once it reaches minAccuracyM. A current record never resets the interval clock.

Uploads and auth

setAuthorization

setAuthorization(auth: Authorization): Promise<void>

Stores upload credentials in secure storage, clears authorizationRequired, and triggers an upload right away (ignoring backoff and any auth pause).

Field	Type
`accessToken`	`string`	Sent as `Authorization: Bearer <accessToken>`. Required.
`refreshToken`	`string`	Optional.
`refreshUrl`	`string`	Optional. POSTed on a 401/403; see Authentication.
`refreshPayload`	`Record<string, string>`	Default `{"refresh_token": "{{refreshToken}}"}`.
`refreshHeaders`	`Record<string, string>`	Optional.

clearAuthorization

clearAuthorization(): Promise<void>

Deletes the stored credentials. Call it on logout.

sync

sync(): Promise<number>

Uploads the queue now, ignoring uploadIntervalSec and backoff. Resolves the number of records uploaded.

getQueueCount

getQueueCount(): Promise<number>

Records waiting to be uploaded.

clearQueue

clearQueue(): Promise<void>

Deletes every queued record.

Permissions and device

requestPermission

requestPermission(level: 'whenInUse' | 'always'): Promise<AuthorizationStatus>

The only call that shows a permission dialog. Shows the OS flow and resolves an AuthorizationStatus. Never shows custom UI: your rationale screen comes first. Android rejects NO_ACTIVITY when there is no foreground Activity. Details per platform in Permissions.

getProviderState

getProviderState(): Promise<ProviderState>

Location services, GPS and network providers, permission status, precise or reduced accuracy, power-save mode and battery-optimization exemption. See ProviderState.

deviceSettings

deviceSettings.isIgnoringBatteryOptimizations(): Promise<boolean>
deviceSettings.requestIgnoreBatteryOptimizations(): Promise<boolean>
deviceSettings.openPowerManagerSettings(): Promise<boolean>
deviceSettings.openAppSettings(): Promise<boolean>
deviceSettings.openLocationSettings(): Promise<boolean>

Method	Android	iOS
`isIgnoringBatteryOptimizations`	The PowerManager answer.	`true`
`requestIgnoreBatteryOptimizations`	Direct prompt if the app declares `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`, else the battery-optimization list. `true` if a screen opened.	`false`
`openPowerManagerSettings`	First OEM power / auto-start screen that exists (Samsung, Xiaomi, Huawei, Oppo/Realme, Vivo, OnePlus, Asus, Letv, Meizu), else app details. `true` if a screen opened.	`false`
`openAppSettings`	App details. `true` if a screen opened.	The app’s Settings page.
`openLocationSettings`	System location settings. `true` if a screen opened.	The app’s Settings page.

See Android battery managers.

Logging

logger.getLog

logger.getLog(options?: GetLogOptions): Promise<string>

Resolves the on-device log as text, one entry per line:

2026-10-26T12:00:00.123Z INFO  [tag] message

Option	Type	Default
`sinceMs`	`number` (epoch ms)	24 hours ago
`limit`	`number`	`1000`
`order`	`'asc' \| 'desc'`	`'asc'`

It returns the newest limit entries since sinceMs, in the requested order. See Troubleshooting.

logger.clear

logger.clear(): Promise<void>

Deletes the log.

Events

onLocation, onMotionChange, onHttp, onProviderChange, onAuthorization, onEnabledChange, onConfigChange and onError each take a callback and return a Subscription with remove(). See Events.