Skip to main content

Integrate the Fairmatic Android SDK

Before You Begin​

We have created a sample app to demonstrate the basic use of the Fairmatic SDK. We have referred to this app in multiple places throughout the documentation. Here is the link for the app.

Requirements​

  • The SDK works for Android API 26 (Oreo) and above.

1. Set up your Android Studio Project​

Add to your Gradle file​

  1. In your app's settings.gradle file, add the following repositories.
pluginManagement {
    repositories {
        mavenCentral()
        // drivequant repository
        maven {
            url "https://maven.drivequant.com/repository/android-sdk/"
        }
        ...
    }
    ...
}
  1. In your module's build.gradle file, add the following dependencies.
...
dependencies {
    implementation 'com.fairmatic:sdk:3.0.2'
    ...
}
  1. Modify the minSdkVersion to 26 if it is currently set lower than 26.
android {
    defaultConfig {
        minSdk 26
    }
}

Your file structure should look like the complete sample tab given below.

apply plugin: 'com.android.application'

android {
    compileSdkVersion 34

    defaultConfig {
        applicationId "com.XXX.XXX"
        minSdkVersion 26
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
    }
    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }

    lintOptions {
        // This is needed to avoid spurious lint errors from libthrift and log4j.
        disable 'InvalidPackage'
    }
    packagingOptions {
        exclude 'META-INF/LICENSE.txt'
        exclude 'META-INF/NOTICE.txt'
    }
}

dependencies {
    ...
    implementation 'com.fairmatic:sdk:3.0.2'
    ...
}

2. Setup the Fairmatic SDK​

To put the SDK into a “ready” state, you’ll first need to set up the Fairmatic SDK properly. This allows for subsequent Insurance Period APIs to be called and for the SDK to start actively capturing information.

You can refer this to see how the setup() has been called. You can also check how the FairmaticDriverAttributes and FairmaticConfiguration objects have been instantiated. In this sample app, the initializeFairmaticSDK() function has been called from two places: the Application class and the LoginFragment.

Input Parameters for Fairmatic.setup()​

The setup() API takes three input parameters:

  • Context
  • FairmaticConfiguration (see below)
  • FairmaticTripNotification

Input Parameters for the FairmaticConfiguration Object​

The specific form of the FairmaticConfiguration object that’s needed for this integration takes three arguments:

  • FAIRMATIC_SDK_KEY
  • Driver ID
  • FairmaticDriverAttributes

Create the FairmaticConfiguration Object​

The FairmaticConfiguration object is used to identify the unique driver that's being tracked by the Fairmatic SDK.

When creating the FairmaticConfiguration object, the following points should be followed:

val fairmaticDriverAttributes = FairmaticDriverAttributes(
    firstName = "John",
    lastName = "Doe",
    email = "john_doe@company.com",
    phoneNumber = "1234567890"
)

val fairmaticConfiguration = FairmaticConfiguration(
    sdkKey = FAIRMATIC_SDK_KEY,
    driverId = "alphanumeric_driver_id",
    driverAttributes = fairmaticDriverAttributes
)
info

Fairmatic requires the driver name as a compulsory parameter when creating FairmaticDriverAttributes for setting up the SDK. Passing an empty string in the driver name will throw an error in the setup API

Customizing fairmatic notification​

Your OS may kill and restart background services from time to time, to either conserve battery or allocate a lot of memory (e.g. to display a large page in the browser). To properly track trips, Fairmatic uses a foreground service when a trip is in progress. To do this, the SDK asks the app for a required notification.

danger
  1. Even after you implement the foreground service, the OS might kill the Fairmatic service if it's under high pressure. This can occasionally result in split or missing trips in your app.
  2. The notification is visible to the user and should contain an appropriate message. Make sure you modify at least the notification ID, channel, and message based on your application needs.

The SDK setup method accepts FairmaticTripNotification instance as one of the parameters. You may configure this object as follows:

val notification = FairmaticTripNotification(
    title = "Fairmatic",
    content = "In Drive",
    iconId = R.drawable.ic_trip_notification
).apply {
    channelId = "fairmatic_sdk_notification_channel"
    channelName = "Fairmatic SDK Notifications"
    notificationId = 75000
    // contentIntent = your custom pending intent for the click action
}
warning

Ensure the iconId is a valid drawable resource id. If no valid resourceId is provided, the notification icon will appear as an empty blob.

Call the setup() API​

After successfully creating the FairmaticConfiguration & FairmaticTripNotification object, you’ll then call the Fairmatic.setup() API in order to put the SDK into a “ready” state. The setup() API should be called before any Insurance APIs are used.

info

You only need to call the setup() API once on your app launch to put the Fairmatic SDK into a "ready" state. There's no need to call it after each subsequent drive.

Below is a sample implementation of how to use the setup API.

Fairmatic.setup(
  context,
  fairmaticConfiguration,
  fairmaticTripNotification,
  object : FairmaticOperationCallback {
      override fun onCompletion(result: FairmaticOperationResult) {
          if (result is FairmaticOperationResult.Success) {
            Log.d("TAG", "FairmaticSDK setup success");
          } else {
            Log.d("TAG", "FairmaticSDK setup failed ${result.getErrorCode().toString()}");
          }
    }
  }
);

Handling setup() API Errors​

The implementation included in this document for the setup() API function handles the FairmaticOperationCallback. You can use that callback to display or hide error notifications for the setup() API. Error codes for setup and other Fairmatic SDK APIs can be found here.

Subscribe to the BOOT_COMPLETED Intent (Optional)

The Fairmatic SDK should be set up whenever the device is rebooted in order to ensure that trip tracking continues to work correctly.

Implement the BOOT_COMPLETED Intent​

The application should create a separate BroadcastReceiver that listens to the BOOT_COMPLETED intent. The BroadcastReceiver will then trigger the Fairmatic SDK setup flow when it receives such an intent.

Test the BOOT_COMPLETED Intent​

Verify that the app is subscribed to the BOOT_COMPLETED intent and restarting the phone automatically triggers Fairmatic setup and any expected Fairmatic callbacks. This can be quickly verified by adding some logs in Fairmatic callbacks.