Skip to main content

Implement Insurance API Calls

As described in Start Here, there are three insurance periods that are required to be tracked in order to capture all relevant data and price insurance accordingly. This section covers all insurance API calls that correspond to these periods.

Here you can see how the FairmaticOperationCallbacks are created and passed on to the functions which call the startDriveWithPeriodX/stopPeriod functions of Fairmatic SDK.

1. Implement FairmaticOperationCallback for Debugging​

In order to debug whether or not the Insurance APIs are being called successfully from your host application, implement the appropriate FairmaticOperationCallback object and function. This will give you feedback on whether the Insurance API was a success or failure upon use.

info

Location permission is mandatory for trip tracking. Please check for LOCATION_PERMISSION_DENIED error.

Below is a sample implementation of this callback.

val fairmaticOperationCallback = object : FairmaticOperationCallback {
    override fun onCompletion(result: FairmaticOperationResult) {
        if (result is FairmaticOperationResult.Failure) {
            Log.d("FairmaticSDKDebug", "Insurance period switch failed, error: ${result.error.name}")
        }
    }
}

2. Insurance Period APIs​

The insurance periods you will be tracking are all represented by APIs within the Fairmatic SDK. These periods along with the corresponding APIs are listed below.

You can see here how these periods are started/stopped on the basis of user actions.

Please use the diagram below to see which periods are relevant to your use case. Accordingly, please only use the relevant sections below.

Insurance Period State Diagram

No Period​

When no Period is in progress, the stopPeriod() API should be called to make sure the SDK is not tracking any rides.

Trigger this API when the driver signals that they want to go "Offline" or when they signal that they aren't actively looking to pick up or match with an occupant.

Fairmatic.stopPeriod(context, insuranceCallback)

If your drivers will drive for other ride-sharing services, you can use the stop period implementation so that coverage is not provided by Fairmatic Insurance during this period. This will prevent you from being charged when the driver isn't driving for your company. We recommend adding a button that calls stopPeriod() whenever the driver is driving for a different service as shown above, and then a resume button to enable tracking via startDriveWithPeriod1() or any other period based on your use case.

Period 1​

If your use case includes Period 1, which is the insurance risk period where drivers are actively looking for occupants to pick up but haven't matched with one yet, then implement the below API. Any driving activity within this period will be manually detected and recorded when this API is in use.

Trigger this API right when the driver has signalled that they're ready to pair with an occupant. This can be them signalling "ready for rides" in a traditional rideshare use case. Usually does not apply to pre-scheduled pick ups.

Fairmatic.startDriveWithPeriod1(context, trackingId, insuranceCallback)

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 a single trip in your system.
This allows for correlation between your backend and the Fairmatic systems.

Period 2​

If your use case includes Period 2, which is the insurance risk period in which drivers are on their way to pick up a passenger or goods, AND there are no passengers or goods in the vehicle, then implement the below API.

Trigger this API right when the driver is on their way to pick up the occupant. This can be a UI trigger or a pre-scheduled trigger depending on the use case.

Fairmatic.startDriveWithPeriod2(context, trackingId, insuranceCallback)

Period 3​

If your use case includes Period 3, which is the insurance risk period in which there is at least one passenger in the vehicle, then implement the below API.

Trigger this API right when the driver has picked up the occupant. This can be a UI trigger.

Fairmatic.startDriveWithPeriod3(context, trackingId, insuranceCallback)

3. Switching Between Insurance APIs​

To switch between Insurance APIs, there's no need to call an intermediate API. You can safely call the subsequent Insurance API to start the next period you're going to.

For example, when switching from Period 2 to Period 3, if you're currently in an ongoing Period 2 trip, you can safely call startDriveWithPeriod3() and the SDK will switch you into Period 3.

4. Testing the Insurance APIs​

After implementing all the Insurance APIs that you'll be using, test each of them to ensure they're in working order. The best way to test is to go through an example use case of your host application.

Use the checklist below to verify your integration is correct. Only use the checklist items that apply to your use case.

  • Does stopPeriod() API trigger any time a driver goes "offline" or when they're not "on-duty"?
  • Does startDriveWithPeriod1() API start a drive when the corresponding signal is given from the host application?
  • Does startDriveWithPeriod2() API start a drive when the corresponding signal is given from the host application?
  • Does startDriveWithPeriod3() API start a drive when the corresponding signal is given from the host application?
  • Does going through an example use case of your host application trigger all the relevant periods properly?