Telematics SDK
A flutter plugin for tracking the person's driving behavior such as speeding, turning, braking and several other things on iOS and Android.
Disclaimer: This project uses Telematics SDK which belongs to DAMOOV PTE. LTD.
When using Telematics SDK refer to these terms of use
Getting Started
Initial app setup & credentials
For commercial use, you need create a developer workspace in DataHub and get InstanceId and InstanceKey auth keys to work with our API.
Android
Please draw attention that Android SDK supports Gradle 8+ versions only.
AndroidManifest.xml
add to file ./app/src/main/AndroidManifest.xml props:
- 'xmlns:tools="http://schemas.android.com/tools"' into manifest tag
- 'tools:replace="android:label"' into __application tag
as shown below:
<manifest
xmlns:tools="http://schemas.android.com/tools">
<application
tools:replace="android:label,android:name">
...
</application>
...
</manifest>
add network permissions
<manifest>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
</manifest>
build.gradle
add to file (module)/build.gradle props:
android {
buildTypes {
release {
shrinkResources false
minifyEnabled false
}
}
}
Proguard
-keep public class com.telematicssdk.tracking.** {*;}
Android Advanced
SetTrackingSettings
- Override application class extends TelematicsSDKApp
import com.telematicssdk.TelematicsSDKApp
class App: TelematicsSDKApp() {
override fun onCreate() {
val api = TrackingApi.getInstance()
api.initialize(this, setTelematicsSettings())
super.onCreate()
}
override fun setTelematicsSettings(): Settings {
val settings = Settings(
stopTrackingTimeout = Settings.stopTrackingTimeHigh,
accuracy = Settings.accuracyHigh,
autoStartOn = true,
elmOn = false,
hfOn = true
)
return settings
}
}
- add to tag application of file ./app/src/main/AndroidManifest.xml this class name:
<application
android:name=".App">
</application>
- add Telematics SDK repository into (module)/build.gradle
dependencies {
implementation "com.telematicssdk:tracking:3.2.0"
}
iOS
Add permissions in your project's ios/Runner/Info.plist:
<key>UIBackgroundModes</key>
<array>
<string>fetch</string>
<string>location</string>
<string>remote-notification</string>
</array>
<key>NSMotionUsageDescription</key>
<string>Please, provide permissions for this Demo</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Please, provide permissions for this Demo</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Please, provide permissions for this Demo</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Please, provide permissions for this Demo</string>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>sdk.damoov.apprefreshtaskid</string>
<string>sdk.damoov.appprocessingtaskid</string>
</array>
Starting from iOS version 15 and above, as well as Flutter 2.0.6, modification of ios/Runner/AppDelegate.swift is required
You must initialize TelematicsSDK before GeneratedPluginRegistrant.
If your app doesn't support SceneDelegate and Flutter version if lower then 3.38, then follow this way:
import Flutter
import UIKit
import TelematicsSDK
@main
@objc class AppDelegate: FlutterAppDelegate {
override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
RPEntry.initializeSDK()
RPEntry.instance.application(application, didFinishLaunchingWithOptions: launchOptions)
GeneratedPluginRegistrant.register(with: self)
return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
}
Otherwise, if Flutter version is 3.38 and higher, then you have to implement UISceneDelegate adoption for the app and follow this way:
import Flutter
import UIKit
import TelematicsSDK
@main
@objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
RPEntry.initializeSDK()
RPEntry.instance.application(application, didFinishLaunchingWithOptions: launchOptions)
return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
func didInitializeImplicitFlutterEngine(_ engineBridge: any FlutterImplicitEngineBridge) {
GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
}
}
A guide for Flutter iOS developers to adopt Apple's UISceneDelegate protocol is here: https://docs.flutter.dev/release/breaking-changes/uiscenedelegate
Enabling and Disabling the SDK
Firstly, create trackingAPI object to interact with SDK
import 'package:telematics_sdk/telematics_sdk.dart';
final trackingApi = TrackingApi();
Login
await trackingApi.setDeviceID(deviceId: 'DEVICE_TOKEN');
Logout
await trackingApi.logout();
Enable the SDK
await trackingApi.setEnableSdk(enable: true);
Disable the SDK
await trackingApi.setEnableSdk(enable: false);
Additional Available Methods
Manual start tracking
await trackingApi.startManualTracking();
Manual start persistent tracking
await trackingApi.startManualPersistentTracking();
Notes: Persistent tracking ignores all stop tracking reasons and continues before 'stopManualTracking' method will be called. Max persistent tracking duration is 10 hours.
Manual stop tracking
await trackingApi.stopManualTracking();
Check SDK initialization state
final initialized = await trackingApi.isInitialized();
Get current device ID
final deviceId = await trackingApi.getDeviceId();
Check all required permissions and sensors
final granted = await trackingApi.isAllRequiredPermissionsAndSensorsGranted();
Check SDK enabled state
final enabled = await trackingApi.isSdkEnabled();
Check RTLD (Real-Time Data Logging) status
final rtldEnabled = await trackingApi.isRTLDEnabled();
Register speed limit violations monitoring
await trackingApi.registerSpeedViolations(
speedLimitKmH: 90.0,
speedLimitTimeout: 60,
);
Listen for speed violations
final sub = trackingApi.speedViolation.listen((event) {
// Handle speed violation
});
Listen for location updates
final sub = trackingApi.locationChanged.listen((location) {
// Handle location update
});
Listen for tracking state changes
final sub = trackingApi.trackingStateChanged.listen((active) {
// true = started, false = stopped
});
Listen for Low Power Mode changes
final sub = trackingApi.lowPowerMode.listen((enabled) {
// Power saving mode changed
});
Upload unsent trips
await trackingApi.uploadUnsentTrips();
Get unsent trips count
final unsentTripsCount = await trackingApi.getUnsentTripCount();
Send a custom heartbeat
await trackingApi.sendCustomHeartbeats(reason: 'CustomHeartbeat');
Tracking status
final isTracking = await trackingApi.isTracking();
Enable Accidents detection Accidents detection is disabled by default. You can enable detection.
await trackingApi.setAccidentDetectionEnabled(value: true);
//to check current accidents status
final isEnabledAccidents = await trackingApi.isAccidentDetectionEnabled();
Change Accident detection sensitivity Accident detection sensitivity is normal by default. You can change sensitivity. Sensitivity options which is available to apply: .normal, .sensitive, .tough
await trackingApi.setAccidentDetectionSensitivity(sensitivity: AccidentDetectionSensitivity.normal);
Create new tag The detailed information about using Tags is available here
String tag = 'TAG';
String source = 'App';
await trackingApi.addFutureTrackTag(tag: tag, source: source);
Remove a tag
String tag = 'TAG';
await trackingApi.removeFutureTrackTag(tag: tag);
Remove all tags
await trackingApi.removeAllFutureTrackTags();
Setting up the permission wizard Without these permissions SDK can not be enabled. If you want to use your own way to request permissions, you can skip this part.
To show the permission wizard, follow next steps:
- Create and init StreamSubscription in your widget
late StreamSubscription<PermissionWizardResult?> _onPermissionWizardStateChanged;
@override
void initState() {
onPermissionWizardStateChanged = trackingApi
.onPermissionWizardClose
.listen(_onPermissionWizardResult);
}
void onPermissionWizardResult(PermissionWizardResult result) {
if (result == PermissionWizardResult.allGranted) {
//All permissions are granted. To do something here.
} else {
//Permissions are not granted. To do something here.
}
}
- Request to show the permission wizard
await trackingApi.showPermissionWizard(
enableAggressivePermissionsWizard: false,
enableAggressivePermissionsWizardPage: true
);
If [enableAggressivePermissionsWizard] set to true the wizard will be finished if all required permissions granted (user can’t cancel it with back button), otherwise if set to false the wizard can be finished with not all granted permissions or cancelled with back button.
If [enableAggressivePermissionsWizardPage] set to true the wizard will slide to next page if requested permissions granted on current page, otherwise if set to false the wizard can slide with not granted permissions.
Available Methods (iOS only)
Check wrong accuracy state (Reduced Accuracy)
final wrongAccuracy = await trackingApi.isWrongAccuracyState();
Request Always Location permission
await trackingApi.requestIOSLocationAlwaysPermission();
Request Motion permission
await trackingApi.requestIOSMotionPermission();
Listen for wrong accuracy events
trackingApi.iOSWrongAccuracyAuthorization.listen((_) {
// Reduced accuracy detected
});
Listen for RTLD events
trackingApi.iOSRTLDDataCollected.listen((_) {
// RTLD data collected
});
Enable/Disable Automatic tracking
bool disableTracking = false;
//true to disable automatic tracking (tracking is enabled by default)
await trackingApi.setDisableTracking(value: disableTracking);
Automatic tracking status
final isTrackingDisabled = await trackingApi.isDisableTracking();
Enable/Disable Aggressive Heartbeats
The telematics SDK (iOS only) supports two operational modes for heartbeats;
Aggressive heartbeats - heartbeats are sent every 20 minutes. SDK is always active. Normal Heartbeats - heartbeats are sent every 20 minutes but when SDK turns into Standby mode, it will be activated only by a new trip, and heartbeat will be sent respectively.
Mode switcher
bool enable = true; //false to disable aggressive heartbeats
await trackingApi.setAggressiveHeartbeats(value: enable)
Check state
final isAggressiveHeartbeats = await trackingApi.isAggressiveHeartbeat()
Available Methods (Android only)
Enable / Disable SDK auto-start
await trackingApi.setAndroidAutoStartEnabled(
enable: true,
permanent: true,
);
Check SDK auto-start status
final autoStartEnabled = await trackingApi.isAndroidAutoStartEnabled();