Skip to main content

Integrate the Fairmatic React Native SDK

Package Installation​

Using npm​

npm install react-native-fairmatic-sdk@3.0.3 --save

Using yarn​

yarn add react-native-fairmatic-sdk@3.0.3

iOS-specific installation steps​

Podfile changes​

In your project's Podfile, add the following lines:

target 'xyz' do
  use_frameworks! # The Fairmatic SDK is provided as a dynamic framework
  # your pods
  ......
  # Add Fairmatic iOS Pod dependency
  # Note that the version should be a minimum of 3.0.0
  pod 'FairmaticSDK', :git => 'https://github.com/fairmatic/fairmatic-cocoapods', :tag => '3.0.1'
  pod 'react-native-fairmatic-sdk', :path => '../node_modules/react-native-fairmatic-sdk'
info

Fairmatic React Native Library needs use_frameworks! which in turn will not work with Flipper. More on this can be read here.

After adding the above to your Podfile, run the Pod installation command:

cd ios & pod install

Background Modes​

Allow background location updates and background fetch for your app: On the project screen, click Capabilities → Turn Background Modes on → Select Location updates and Background Fetch

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
	<string>com.fairmatic.sdk.bgrefreshtask</string>
</array>

If your app does not already have them, please include the following keys in your app's Info.plist

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need background location permission to provide you with
driving analytics</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need background location permission to provide you with
driving analytics</string>
<key>NSMotionUsageDescription</key>
<string>We use activity to detect your trips faster and more accurately.
This also reduces the amount of battery we use.</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Bluetooth</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>Bluetooth</string>
tip

Even though we won't actually use Bluetooth features, Apple requires this message whenever Bluetooth code is present in an app. This is just a technical requirement.

Android-specific installation steps​

  1. Update your minSdk to 26. Based on your project setup, it could either be found under buildScript -> ext block or directly under android -> defaultConfig block in your build.gradle file
  2. Add DriveQuant maven repository
repositories {
    maven {
        url "https://maven.drivequant.com/repository/android-sdk/"
    }
}

Setup the SDK​

The SDK setup should be done as soon as your app launches. The following code snippet shows the setup process.

// Attributes of the driver
const driverAttributes: DriverAttributes = {
  firstName: "John",
  lastName: "Doe",
  email: "john.doe@example.com",
  phoneNumber: "123-456-7890",
};

// Configure the trip notification
const fairmaticNotification: FairmaticTripNotification = {
  title: "Fairmatic Trip",
  content: "Monitoring a trip",
  iconResourceName: "fm_car",
};

// Configurations for the driver
const fairmaticConfiguration: FairmaticConfiguration = {
  sdkKey: "your_sdk_key_here",
  driverId: "your_driver_id",
  driverAttributes: driverAttributes,
  notification: fairmaticNotification
};

// Calling the setup with the above FairmaticConfiguration variable as the param
FairmaticSDK.setup(fairmaticConfiguration)
  .then((result: FairmaticOperationResult) => {
    console.log("response: ", result);
    if (result.isSuccess) console.log("Setup Succesful");
    else console.log("Setup Failed because of ", result.errorMessage);
  })
  .catch((error: any) => {
    console.error("Error setting up Fairmatic SDK:", error);
  });

In the above sample code, the SDK key needed to set up the SDK can be obtained from here.

Insurance Period Calls​

There are three Insurance Risk Periods, as defined by the California Public Utilities Commission:

  • Period 1: The driver is logged into the mobile application, and is available for ride requests, but has not been matched with an occupant.
  • Period 2: The driver has accepted a match but the driver’s vehicle is not yet occupied.
  • Period 3: The driver has completed the pick-up and the driver’s vehicle is occupied.

The following sections highlight how to make the insurance period API calls.

Insurance period 1 ​

FairmaticSDK.startDriveWithPeriod1(your_trip_tracking_id).then(result => {
    console.log(result);
});

trackingId parameter explained:​

info

The trackingId parameter accepts an alphanumeric string. While it is recommended to use a unique string for each startPeriod() call for this parameter, uniqueness is not mandatory.

This string serves as an identifier to search for trips using the server APIs provided by Fairmatic. We recommend formatting your trackingId in a way that facilitates easy matching of trips between our system and your backend systems.

An example use case for trackingId: Consider a scenario where you store insurance periods (P2, P3) of a single trip as one trip in your backend. In the Fairmatic system, these periods are stored as separate trips. By passing the same trackingId for both the startPeriod2() and startPeriod3() API calls, you can map the P2 and P3 trips in the Fairmatic backend to the single trip in your system. This allows for correlation between your backend and the Fairmatic systems.

Insurance period 2 ​

FairmaticSDK.startDriveWithPeriod2(your_trip_tracking_id).then(result => {
    console.log(result);
});

Insurance period 3 ​

Please refer to this explanation for the trackingId parameter in this API.

FairmaticSDK.startDriveWithPeriod3(your_trip_tracking_id).then(result => {
    console.log(result);
});

Stop period ​

FairmaticSDK.stopPeriod().then(result => {
    console.log(result);
});

Disabling the SDK ​

The teardown() API can be used to disable the SDK. Please note that this API should be called only when the driver logs out of the application.

FairmaticSDK.teardown().then(result => {
    console.log(result);
});