Examples

Install the module

Run the following command to install the module (make sure to install the core and crash-detection modules beforehand):

npm i @sentiance-react-native/legacy

Import the module

import RNSentiance from "@sentiance-react-native/legacy";

You can find a reference to all the types mentioned on this page here.

Initialize the SDK and create a user

Without User Linking

const shouldStart = true; // start the SDK too
// returns Promise<boolean | SdkStatus>
const result = await RNSentiance.init(appId, secret, baseUrl, shouldStart);

With User Linking

const emitter = new NativeEventEmitter(RNSentiance);

emitter.addListener('SDKUserLink',
      async data => {
        const { installId } = data;
        const success = await linkUserToYourBackend(installId);
        RNSentiance.userLinkCallback(success);
      }
    );

const shouldStart = true; // start the SDK too
// returns Promise<boolean | SdkStatus>
const result = await RNSentiance.initWithUserLinkingEnabled(
    appId, secret, baseUrl, shouldStart);

Starting the SDK

// returns Promise<SdkStatus>
const result = await RNSentiance.start();

You can also enable detections while also setting a future expiry date for the SDK to stop automatically:

const expiryDate = Date.now() + 60 * 60 * 1000; // 1 hour from now
// returns Promise<SdkStatus>
const result = await RNSentiance.startWithStopDate(expiryDate);

Stopping the SDK

While it's possible to "pause" the detections of the Sentiance SDK's, it's not recommended, as it can lead to missed detections (e.g. trips).

try {
  // returns Promise<boolean>
  const result = await RNSentiance.stop();
  // SDK stopped properly.
} catch (err) {
  // An error prevented the SDK from stopping correctly
}

Init status

Checking if SDK is initialized:

// returns Promise<SdkInitState>
const initState = await RNSentiance.getInitState();
const isInitialized = initState == "INITIALIZED";

SDK status

Getting the status of the SDK:

// returns Promise<SdkStatus>
const sdkStatus = await RNSentiance.getSdkStatus();

The SDK can signal SDK status updates to JavaScript without being invoked directly. You can subscribe to these status updates:

import { NativeEventEmitter } from "react-native";

const sentianceEmitter = new NativeEventEmitter(RNSentiance);
const subscription = sentianceEmitter.addListener(
  "SENTIANCE_STATUS_UPDATE_EVENT", (res) => {
  // Returns SDK status
});

// Don't forget to unsubscribe, typically in componentWillUnmount
subscription.remove();

Get the SDK version

// returns Promise<string>
const version = await RNSentiance.getVersion();

Get the user ID

If the SDK is initialized, you can get the user ID as follows. This user ID will allow you to interact with the APIs from Sentiance. You need a token and a user ID to authorize requests and query the right data.

// returns Promise<string>
const userId = await RNSentiance.getUserId();

Get the user access token

If the SDK is initialized, you can get a user access token as follows. This token will allow you to interact with the APIs from Sentiance. You need a token and a user ID to authorize requests and query the right data. If the token has expired, or will expire soon, the SDK will get a new bearer token before returning it. Generally, this operation will complete instantly by returning a cached bearer token, but if a new token has to be obtained from the Sentiance API, there is a possibility that it will fail

// returns Promise<UserAccessToken>
const { tokenId } = await RNSentiance.getUserAccessToken();

Adding custom metadata

Custom metadata allows you to store text-based key-value user properties on the Sentiance platform, such as application related properties, which you can then obtain when processing data offloads (generated by Sentiance).

const label = "correlation_id";
const value = "3a5276ec-b2b2-4636-b893-eb9a9f014938";

// returns Promise<boolean>
await RNSentiance.addUserMetadataField(label, value);

Remove custom metadata

You can remove previously added metadata fields by passing the metadata label to the removeUserMetadataField function.

const label = "correlation_id";

// returns Promise<boolean>
await RNSentiance.removeUserMetadataField(label);

Adding multiple custom metadata fields

You can add multiple custom metadata fields by passing an object to the addUserMetadataFields function.

const metadata = { corrolation_id: "3a5276ec-b2b2-4636-b893-eb9a9f014938" };

// returns Promise<boolean>
await RNSentiance.addUserMetadataFields(metadata);

Starting trip

When you call startTrip on the SDK, you override automatic SDK detections and force trip data collection, until you call stopTrip, or until the trip times out (only applicable to the triggered trip SDK flavor). startTrip accepts a metadata object and a transport mode hint (numeric) as parameters.

Transport mode hint:

export enum TransportMode {
    UNKNOWN = 1,
    CAR,
    BICYCLE,
    ON_FOOT,
    TRAIN,
    TRAM,
    BUS,
    PLANE,
    BOAT,
    METRO,
    RUNNING
}

Example:

const metadata = { corrolation_id: "3a5276ec-b2b2-4636-b893-eb9a9f014938" };
const transportModeHint = 1;

try {
  // returns Promise<boolean>
  await RNSentiance.startTrip(metadata, transportModeHint);
  // Trip is started
} catch (err) {
  // Unable to start trip
}

Stopping trip

try {
  // returns Promise<boolean>
  const trip = await RNSentiance.stopTrip();
  // Stopped trip
} catch (err) {
  // Unable to stop trip
}

You can also receive trip timeout events:

import { NativeEventEmitter } from "react-native";

const sentianceEmitter = new NativeEventEmitter(RNSentianceLibrary);
const subscription = sentianceEmitter.addListener("TripTimeout", () => {
  // Trip timeout received
});

Trip status

Checking an ongoing trip status:

// returns Promise<boolean>
const isTripOngoing = await RNSentiance.isTripOngoing();

Control sending data

If you want to override the default SDK data submission behavior, you can initiate a forced submission of detections. Ideally, you use this method only after explaining to the user that your app will consume more bandwidth in case the device is not connected to Wi-Fi.

try {
  // returns Promise<boolean>
  await RNSentiance.submitDetections();
} catch (err) {
  // Something went wrong with submitting data, for more information, see the error variable
}

Disk, mobile network and Wi-Fi quotas

The usage and limits of network and disk capacity in bytes can be obtained using the getWiFiQuotaUsage, getWiFiQuotaLimit and similar methods on the Sentiance SDK interface.

// returns Promise<string>
const limit = await RNSentiance.getWiFiQuotaLimit();

All quota functions:

• getWiFiQuotaLimit

• getWiFiQuotaUsage

• getMobileQuotaLimit

• getMobileQuotaUsage

• getDiskQuotaLimit

• getDiskQuotaUsage

User Activity

To get the user's current activity:

// returns Promise<UserActivity>
const userActivity = await RNSentiance.getUserActivity();

You can subscribe to receive user activity updates:

import { NativeEventEmitter } from "react-native";

const sentianceEmitter = new NativeEventEmitter(RNSentiance);
const subscription = sentianceEmitter.addListener(
  "SDKUserActivityUpdate",
  (userActivity) => {
    // Handle user activity
  }
);

RNSentiance.listenUserActivityUpdates();

// Don't forget to unsubscribe, typically in componentWillUnmount
subscription.remove();

Handling user activity:

const { type, tripInfo, stationaryInfo } = userActivity;

if (type === "USER_ACTIVITY_TYPE_STATIONARY") {
  const { location } = stationaryInfo;

  if (location) {
    const { latitude, longitude } = location;
  }
  //..
} else if (type === "USER_ACTIVITY_TYPE_TRIP") {
  //..
} else if (type === "USER_ACTIVITY_TYPE_UNKNOWN") {
  //..
}

Update the SDK foreground notification (ANDROID ONLY)

Updates the title and text of SDK notification. After calling this method, any notification shown by the SDK will be updated.

Note that this change is valid only during the process's lifetime. After the app process restarts, the SDK will display the default notification.

// returns Promise<boolean>
await RNSentiance.updateSdkNotification("RN SDK Sample", "SDK is running");

Resetting the SDK

To delete the Sentiance user and its data from the device, you can reset the SDK by calling RNSentiance.clear. This allows you to create a new Sentiance user by reinitializing the SDK, and linking it to a new external ID.

try {
  // returns Promise<boolean>
  await RNSentiance.clear();
  // The SDK was successfully cleared and reset
} catch (err) {
  // Resetting the SDK failed
  // err.name has three values: SDK_INIT_IN_PROGRESS, SDK_RESET_IN_PROGRESS, SDK_RESET_UNKNOWN_ERROR
}

Determine if the app should initialize Sentiance SDK natively

To make user linking possible, the first SDK initialization should be executed in JS. After it completes successfully, await RNSentiance.enableNativeInitialization() should be invoked.

In AppDelegate (iOS) and MainApplication (Android), isNativeInitializationEnabled can be used to determine if the SDK should be initialized natively.

To disable native initialization, invoke await RNSentiance.disableNativeInitialization().

Please refer to our example app for a complete usage.

Vehicle Crash Event Detection

Listen to vehicle crash events:

import { NativeEventEmitter } from "react-native";

const sentianceEmitter = new NativeEventEmitter(RNSentiance);
const vehicleCrashEventSubscription = sentianceEmitter.addListener(
  "VehicleCrashEvent",
  (event: VehicleCrashEvent) => {}
);

RNSentiance.listenVehicleCrashEvents();

// To unsubscribe
vehicleCrashEventSubscription.remove();

Invoke a dummy vehicle crash event

// returns Promise<boolean>
await RNSentiance.invokeDummyVehicleCrash();

Check if crash detection is supported

// returns Promise<boolean>
const crashDetectionSupported =
  await RNSentiance.isVehicleCrashDetectionSupported("TRIP_TYPE_SDK");
if (crashDetectionSupported) {
  // setup vehicle crash event listener
}

Disable battery optimization (Android)

// returns Promise<boolean>
await SentianceCore.disableBatteryOptimization();