Incident reporting

The Leeo SDK provides APIs that the client application can call to start the incident reporting flow. The driver can use this flow to report any incidents and record related details when they are performing duties.

Overview

The Leeo SDK offers two main methods for incident reporting:

1. Opening in Default Browser: Recommended approach that opens the incident reporting page in the device's default browser
2. Getting URL for In-App Browser: Alternative approach for apps that already have required permissions mentioned in this section

Prerequisites

Important

Make sure you have set up the SDK using the Fairmatic.setup() method before calling any incident reporting methods, otherwise you will receive a FairmaticError.SDK_NOT_SETUP error.

SDK Methods

1. Open Incident Reporting Web Page

Opens the incident reporting web page in the device's default browser. This is the recommended approach as it allows users to grant the required permissions to the browser instead of your app. Refer to this method in the API documentation for additional details.

loadingProgressBar.visibility = View.VISIBLE   // Show a loader as the method can take some time to open the browser
Leeo.openIncidentReportingWebPage(requireContext()) { result ->
    loadingProgressBar.visibility = View.GONE   // Hide the loader
    if (result is FairmaticOperationResult.Failure) {
        println("Failed to open incident reporting page: ${result.errorCode} - ${result.message}")
    } else {
        println("Incident reporting page opened successfully")
    }
}

When to Use

• When your app doesn't have camera, microphone, speech transcription, or location permissions
• For the best user experience (recommended approach)
• When you want to avoid requesting sensitive permissions in your app

Parameters

• context: the caller's context
• fairmaticOperationCallback: Callback that receives a result
  • If successful: error is null
  • If failed: error contains a FairmaticErrorCode

2. Get Incident Reporting URL

Returns the URL of the incident reporting web page that can be used to open the page in an in-app browser or webview. Refer to this method in the API documentation for additional details.

Required Permissions to use this method:

• Camera: For capturing photos of incidents
• Microphone: For recording audio descriptions
• Speech Transcription: For converting speech to text
• Location: For recording incident location

Fairmatic.getIncidentReportingURL(context) { urlString, errorCode ->
    if (errorCode != null) {
        println("Failed to get incident reporting URL: $errorCode")
    } else if (urlString != null) {
        // Use the URL to open in your in-app browser or WebView
        println("Incident reporting URL: $urlString")
        // Example: openWebView(urlString)
    }
}

When to Use

• When your app already has all required permissions (camera, microphone, speech transcription, location)
• When you want to keep users within your app experience
• For custom in-app browser implementations

Parameters

• context: the caller's context
• fairmaticOperationCallback: Callback that receives two parameters:
  • urlString: Optional String containing the incident reporting URL
  • errorCode: Optional FairmaticErrorCode indicating success/failure

Important Notes

URL Validity

• The URL returned is valid only for a limited time
• Do not cache or store the URL for long-term use
• Fetch a new URL each time you need to open the incident reporting page

Permissions

As mentioned above, your app should have related permission entries in the AndroidManifest.xml file as well as have the permissions. If the above isn't true, the app might exhibit runtime crashes when the incident reporting web page tries to execute the functionality related to these permissions.

Error Handling

Common errors you might encounter:

Error	Description	Solution
FairmaticError.SDK_NOT_SETUP	SDK not properly initialized	Call Fairmatic.setup() first
FairmaticError.NETWORK_NOT_AVAILABLE	Check internet connectivity and retry
FairmaticError.INCIDENT_REPORTING_FEATURE_NOT_ENABLED	The incident reporting feature is not enabled for the organization	Please contact Leeo support team with your SDK key

Best Practices

1. Use Default Browser First: Always prefer openIncidentReportingWebPage unless you specifically need in-app browsing
2. Don't Cache URLs: Always fetch a fresh URL when using getIncidentReportingURL

Troubleshooting

Common Issues

Q: Getting FairmaticError.SDK_NOT_SETUP error A: Ensure you've called Fairmatic.setup() with right parameters and it completed successfully before calling incident reporting methods.

Q: Incident reporting page doesn't load properly in in-app browser A: Check that your app has all required permissions. If not, use openIncidentReportingWebPage instead.

Q: URL expires A: This is expected behavior. Always fetch a new URL each time you want to open the incident reporting page rather than storing the URL.