Pub Version

Flutter HyperTrack SDK is a wrapper around native iOS and Android SDKs that allows to integrate them into Flutter apps.


Basic integration

Migrating from older versions? Check the Migration guide

Add HyperTrack SDK to your project

We constantly work on making our SDKs better, so make sure you have the latest version. You can get it in the changelog here.

Add following lines to your applications pubspec.yml:

  hypertrack_plugin: <version>


Enable Background Modes
Add purpose strings

Set up silent push notifications

Silent push notifications enable HyperTrack Routes to wake up the app when a an Order is dispatched for the driver. For this purpose, the iOS SDK uses APNs silent remote notifications and Android SDK uses FCM silent notifications.

Disable swizzling if you use Firebase on iOS

HyperTrack SDK uses method swizzling that conflicts with the swizzling used by Flutter Firebase library for iOS.

Update Info.plist

Add this HyperTrackSwizzlingEnabled with NO value to your Info.plist

Update AppDelegate

Override the methods from sample above in your AppDelegate:


import HyperTrack

@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)

  override func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
  ) {
    super.application(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)

  override func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
  ) {
    HyperTrack.didReceiveRemoteNotification(userInfo, fetchCompletionHandler: completionHandler)
      didReceiveRemoteNotification: userInfo,
      fetchCompletionHandler: completionHandler

  override func application(
    _ application: UIApplication,
    didFailToRegisterForRemoteNotificationsWithError error: Error
  ) {
    super.application(application, didFailToRegisterForRemoteNotificationsWithError: error)

Set the publishable key

Get your publishable key from the Setup page.

Grant the permissions to the app

Start tracking

Now the app is ready to be tracked from the cloud.

You will need the device id to start tracking, check the Identify devices section for instructions on how to get it.

Follow the Start Tracking tutorial to learn how to control device tracking from your backend.


Once your app is running, go to the dashboard where you can see a list of all your devices and their live location with ongoing activity on the map.

Prepare for App Store and Google Play submission

Recommended additional steps

Identify devices

All devices tracked on HyperTrack are uniquely identified using UUID. You can get this identifier programmatically in your app by calling getDeviceId().


The device ID is changed on each app re-install or clearing the app data

Another approach to identification is to tag devices with names that will make it easy to distinguish them on HyperTrack Dashboard.

HyperTrack.setName("Device name")

You can additionaly tag devices with custom metadata (and filter them in the Dashboard using metadata fields). Metadata should be representable in JSON.

Metadata should be representable with a map of JSON data types. You have to convert it to Json datatype before setting:

JSONObject metadata = JSONObject({
  "key": JSONString("value")


Handle errors

Use the errors subscription to make sure that when the driver navigates to the screen where tracking is supposed to happen, there are no blockers that can prevent that.

You can use subscription API to be able to react immediately when errors come up:

HyperTrack.errors.forEach((error) {
	switch(error) {

HyperTrack.errorsSubscription.listen((errors) {
  errors.forEach((error) {
    switch(error) {

Check the API docs to get the full list of errors.

Migration Guide

From version < 1.0.0

Check the Changelog for more info

From version < 2.0.0

The release of HyperTrack Flutter SDK 2.0.0 is a major update that has a bunch of new improvements. We highly recommend upgrading, but please note that there are a few breaking changes.

The key advantages of the new version are:

User-friendly API:
The revamped static API is the highlight, standing out for its unmatched simplicity, ease of use, and conciseness.

Enhanced Responsiveness & Speed:
Experience quicker time to the first location and minimized system latency.

Superior Tracking Performance:
Delight in the improved quality, granularity, and accuracy of the location event stream.

Optimized Battery Efficiency:
Our refined tracking algorithm reduces unnecessary network calls, preserving battery life.

Decreased Binary Size:
The library's size optimization ensures a more compact overall app footprint.

You can check the detailed Changelog here

The key breaking changes are:

Setting the publishable key

There is no need to initialize the SDK by setting publishable key. The Basic integration instructions decribe the new way of setting it.

Static API

The SDK API was fully redesigned to be more ergonomic and to require less code to use.

All the API methods can be accessible at any time from any place in the app by calling them on the static HyperTrack class.

Check the Changelog for the renamed methods.

Motion activity permission is no longer required

While the SDK still can benefit from Motion activity data to get better accuracy, requesting this permission is now optional.

The corresponsive items of HyperTrackError are removed from the API.

SDK Sync

The SDK is now automatically syncs with the servers, so the sync() method is not needed. You can safely remove it and all the logic related to it.


For a full SDK API reference see HyperTrack Flutter SDK Reference

SDK integration examples

To learn more about SDK integration examples, you may visit these resources:

Quickstart apps

Frequently Asked Questions