This module brings the Traccar Client SDK to React Native applications. It provides background location tracking on Android and iOS, uploading positions over the same simple HTTP protocol used by Traccar and compatible servers. The module is a thin layer over the native SDK, so its behavior, configuration, and reliability characteristics are those described on the main SDK page; this guide covers what is specific to React Native.
The module supports Android API level 24 and above and iOS 15 and above.
Install the package and, on iOS, install the pods:
npm install react-native-traccar-client-sdk
cd ios && pod install
On Android the native SDK is pulled from Maven Central automatically. On iOS the module links the Kotlin/Native TraccarClientSDK framework, which the podspec downloads from the matching GitHub release during pod install.
Initialize the tracker with a configuration that specifies the server address and a device identifier, then start it. Initialization is idempotent, so it is safe to call on every launch; use setConfig afterwards to change settings on a tracker that is already running.
import * as Traccar from 'react-native-traccar-client-sdk';
await Traccar.init({
serverUrl: 'https://demo.traccar.org',
deviceId: '123456',
});
await Traccar.start();
Call Traccar.stop() to stop tracking. Starting requires location permission; if it is denied, start rejects.
The module exposes the full SDK surface as promise-returning functions:
init(config) initializes the tracker, and is safe to call repeatedly.setConfig(config) replaces the configuration of a running tracker.start() begins tracking, requesting any missing permissions first.stop() stops tracking while retaining the saved configuration.requestPosition(alarm?) takes a single fix and uploads it independently of start and stop, resolving with whether the upload succeeded. The optional alarm tags the report with the Traccar alarm field.isTracking() resolves with whether tracking is currently active.getLogs() returns recent diagnostic entries, each with a timestamp in milliseconds and a message.clearLogs() empties the diagnostic log.The SDK does not push events to JavaScript; the current state and logs are read on demand through isTracking and getLogs.
The Config object accepts the same fields as the native SDK. It contains a location object with the location pipeline parameters, a buffer flag that switches between reliable queued upload and real-time-only delivery, the Android-only wakeLock and preferPlatformProviders options, and a notification object for the Android foreground-service text. The accuracy level is given as one of 'HIGHEST', 'HIGH', 'MEDIUM', or 'LOW'.
See the main SDK page for the full configuration reference, including every field, its default value, and how the accuracy levels map to each platform.
The native SDK is built with a newer version of Kotlin than the one React Native's Gradle toolchain currently pins, and it brings a newer kotlin-stdlib into the whole build. Until React Native catches up, the host application must relax the Kotlin metadata check across the build. Add the following to the application's root android/build.gradle:
allprojects {
tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
compilerOptions {
freeCompilerArgs.add("-Xskip-metadata-version-check")
}
}
}
The module already compiles with this flag; the block above extends it to the application's own Kotlin sources and any other Kotlin libraries in the build.
On Android the SDK declares the permissions it needs, and the runtime prompts are presented when tracking starts, so no manifest changes are required.
On iOS, add the usage descriptions to your app's Info.plist - NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, and NSMotionUsageDescription - and enable the Location updates background mode. If you set heartbeatIntervalSeconds, also add fetch to the background modes and register org.traccar.client.heartbeat under BGTaskSchedulerPermittedIdentifiers.