Telematics SDK

A React Native wrapper for tracking the person's driving behavior such as speeding, turning, braking and several other things on iOS and Android.

Disclaimer: This project uses Telematics SDK which belongs to DATA MOTION PTE. LTD. When using Telematics SDK refer to these terms of use

Here you can find short video guides, how to add React Native Telematics SDK to your iOS and Android apps:

Example app

To run a TelematicsSdkExample application make sure that you have Node.js LTS version installed or install it from the official Node.js site. Also, make sure that you correctly configured the development environment according to React Native site instructions.

TelematicsSdkExample application is located in example directory

Inside the project folder install dependencies

yarn

To run an Android example

yarn example android

     -- or --

cd example
npx react-native run-android

To run an iOS example

yarn example ios

     -- or --

cd example
npx react-native run-ios

Installation

yarn add react-native-telematics

Getting started

Initial app setup & credentials

For commercial use, you need create a developer workspace in DataHub and get InstanceId and InstanceKey auth keys to work with our API.

Android

Add permissions in your project's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Remove from your app AndroidManifest.xml line:

    android:allowBackup="true"

Add repository into (module)/gradle.build

dependencies {
    //...
    implementation "com.telematicssdk:tracking: x.x.x"
}

iOS

Add permissions in your project's ios/Runner/Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>location</string>
    <string>remote-notification</string>
</array>
<key>NSMotionUsageDescription</key>
<string>Please, provide permissions for this Demo</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Please, provide permissions for this Demo</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Please, provide permissions for this Demo</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Please, provide permissions for this Demo</string>

In iOS 13 and later, adding a BGTaskSchedulerPermittedIdentifiers key to the Info.plist disables the application:performFetchWithCompletionHandler: and setMinimumBackgroundFetchInterval: methods.

<key>BGTaskSchedulerPermittedIdentifiers</key>
		<array>
    	<string>sdk.damoov.apprefreshtaskid</string>
    	<string>sdk.damoov.appprocessingtaskid</string>
		</array>

And run in your project ios folder:

pod install

Lifecycle handlers

Proper application lifecycle handling is extremely important for the TelematicsSdk. In order to use SDK you need to add lifecycle handlers to your application AppDelegate and Scene Delegate:

App and Scene delegate methods

import TelematicsSDK


//AppDelegate
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    RPEntry.initializeSDK()
    RPEntry.instance.application(application, didFinishLaunchingWithOptions: launchOptions)
    return true
}

func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {
    RPEntry.instance.application(application, handleEventsForBackgroundURLSession: identifier, completionHandler: completionHandler)
}

func applicationDidReceiveMemoryWarning(_ application: UIApplication) {
    RPEntry.instance.applicationDidReceiveMemoryWarning(application)
}

func applicationWillTerminate(_ application: UIApplication) {
    RPEntry.instance.applicationWillTerminate(application)
}

func application(_ application: UIApplication, performFetchWithCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    RPEntry.instance.application(application) {
        completionHandler(.newData)
    }
}

If you use AppDelegate, then you have to implement next methods:

func applicationDidEnterBackground(_ application: UIApplication) {
    RPEntry.instance.applicationDidEnterBackground(application)
}

func applicationWillEnterForeground(_ application: UIApplication) {
    RPEntry.instance.applicationWillEnterForeground(application)
}

func applicationDidBecomeActive(_ application: UIApplication) {
    RPEntry.instance.applicationDidBecomeActive(application)
}

If you use SceneDelegate, then you have to implement next methods:

func sceneDidBecomeActive(_ scene: UIScene) {
    RPEntry.instance.sceneDidBecomeActive(scene)
}

func sceneWillEnterForeground(_ scene: UIScene) {
    RPEntry.instance.sceneWillEnterForeground(scene)
}

func sceneDidEnterBackground(_ scene: UIScene) {
    RPEntry.instance.sceneDidEnterBackground(scene)
}

React Native wrapper usage

import TelematicsSdk, {
  AccidentDetectionSensitivity,
  ApiLanguage,
  addOnLowPowerModeListener,
  addOnLocationChangedListener,
  addOnTrackingStateChangedListener,
  addOnWrongAccuracyAuthorizationListener,
  addOnRtldColectedData,
  addOnSpeedViolationListener,
} from "react-native-telematics";

SDK initializing

// Must be called before any other API
await TelematicsSdk.initialize();

// Returns whether the native SDK is initialized
const initialized = await TelematicsSdk.isInitialized();

Device Id (virtual token)

// Get current device id/token
const deviceId = await TelematicsSdk.getDeviceId();

// Set device id/token
await TelematicsSdk.setDeviceId("YOUR_DEVICE_ID");

Logout

// Performs a full logout and disable SDK
await TelematicsSdk.logout();

Permissions & Sensors

// Checks whether all required permissions and sensors are granted/available
const allGranted = await TelematicsSdk.isAllRequiredPermissionsAndSensorsGranted();

// Shows the native permissions wizard UI
// Returns `true` when all required permissions are granted after the wizard
const isGranted = await TelematicsSdk.showPermissionWizard(false, false);

Enabling and disabling SDK

// Enable or disable SDK globally
await TelematicsSdk.setEnableSdk(true);
await TelematicsSdk.setEnableSdk(false);

// Check SDK enabled status
const isEnabled = await TelematicsSdk.isSdkEnabled();

Tracking

// Start tracking
await TelematicsSdk.startManualTracking();

// Start persistent tracking (continues across background/app restarts)
await TelematicsSdk.startManualPersistentTracking();

// Stop tracking
await TelematicsSdk.stopManualTracking();

// Check tracking state
const tracking = await TelematicsSdk.isTracking();

Trips

// Upload locally stored, unsent trips
await TelematicsSdk.uploadUnsentTrips();

// Get number of unsent trips stored locally
const unsentTripCount = await TelematicsSdk.getUnsentTripCount();

Heartbeats

// Send custom heartbeat with an app-defined reason
await TelematicsSdk.sendCustomHeartbeats("RN_HEARTBEAT_TEST");

Future Tags API

// Add future tag
const addResult = await TelematicsSdk.addFutureTrackTag("future_tag_name", "future_tag_source");

// Get all future tags
const tagsResult = await TelematicsSdk.getFutureTrackTags();

// Remove single future tag
const removeResult = await TelematicsSdk.removeFutureTrackTag("future_tag_name");

// Remove all future tags
const clearResult = await TelematicsSdk.removeAllFutureTrackTags();

Accident detection

// Enable or disable accident detection
await TelematicsSdk.enableAccidents(true);
await TelematicsSdk.enableAccidents(false);

// Check accident detection status
const accidentsEnabled = await TelematicsSdk.isEnabledAccidents();

// Set accident detection sensitivity
await TelematicsSdk.setAccidentDetectionSensitivity(AccidentDetectionSensitivity.Normal);
await TelematicsSdk.setAccidentDetectionSensitivity(AccidentDetectionSensitivity.Sensitive);
await TelematicsSdk.setAccidentDetectionSensitivity(AccidentDetectionSensitivity.Tough);

RTLD (Real-Time tracking)

// Check whether RTLD (real-time data logging) is enabled
const rtldEnabled = await TelematicsSdk.isRTLDEnabled();

Speed violations

// Configure speed limit monitoring
await TelematicsSdk.registerSpeedViolations({
  speedLimitKmH: 80,
  speedLimitTimeout: 10, // seconds
});

Events (listeners)

All listeners return a subscription with .remove().

Low Power Mode (iOS only)

const lowPowerSub = addOnLowPowerModeListener(({ enabled }) => {
  console.log("Low power mode:", enabled);
});

// Don't forget to remove listener
lowPowerSub.remove();

Location changed (cross-platform)

const locationSub = addOnLocationChangedListener(({ latitude, longitude }) => {
  console.log("Location:", latitude, longitude);
});

// Don't forget to remove listener
locationSub.remove();

Tracking state changed (cross-platform)

const trackingSub = addOnTrackingStateChangedListener((state) => {
  console.log("Tracking state:", state);
});

// Don't forget to remove listener
trackingSub.remove();

Speed violation (cross-platform)

const speedSub = addOnSpeedViolationListener((event) => {
  console.log("Speed violation:", event);
});

// Don't forget to remove listener
speedSub.remove();

Wrong accuracy authorization (iOS only)

const wrongAccuracySub = addOnWrongAccuracyAuthorizationListener(() => {
  console.log("Wrong accuracy authorization (iOS)");
});

// Don't forget to remove listener
wrongAccuracySub.remove();

RTLD data collected (iOS only)

const rtldCollectedSub = addOnRtldColectedData(() => {
  console.log("RTLD data collected (iOS)");
});


// Don't forget to remove listener
rtldCollectedSub.remove();

Platform specific

iOS specific

// Get / set API language (iOS only)
const apiLanguage = await TelematicsSdk.getApiLanguage();
await TelematicsSdk.setApiLanguage(ApiLanguage.english);

// Aggressive heartbeat mode (iOS only)
const aggressive = await TelematicsSdk.isAggressiveHeartbeat();
await TelematicsSdk.setAggressiveHeartbeats(true);
await TelematicsSdk.setAggressiveHeartbeats(false);

// Disable user-initiated tracking (iOS only)
await TelematicsSdk.setDisableTracking(true);
const isDisabled = await TelematicsSdk.isDisableTracking();

// Wrong accuracy state (iOS only)
const wrongAccuracyState = await TelematicsSdk.isWrongAccuracyState();

// Request iOS permissions (iOS only)
await TelematicsSdk.requestIOSLocationAlwaysPermission();
await TelematicsSdk.requestIOSMotionPermission();

Android specific

// Configure SDK autostart (Android only)
await TelematicsSdk.setAndroidAutoStartEnabled({ enable: true, permanent: true });
const autoStartEnabled = await TelematicsSdk.isAndroidAutoStartEnabled();