MOTIONTAG SDK Flutter Plugin

The MOTIONTAG Mobility & Location Analytics SDK enables to collect raw sensor data of the telephone in a battery efficient way. This data is then transmitted to the MOTIONTAG back-end system (ISO 27001 certified). In the backend, the sensor events are processed and a partial journey is constructed. Journeys consist either solely of tracks or tracks plus stays. Tracks describe a movement from a origin to a destination with a certain mode of transport. Stays symbolize a stationary behaviour with a particular purpose for the visit.

The use cases for the SDK are manifold. In the mobility sector it can be used to get detailed mobility data for planning purposes. The collected data enables to compare how the transport network is being used. This way the effectiveness of the current infrastructure and the passenger flow management is measured and the design of new mobility services. By implementing and using the SDK you can make use of these findings to improve timetables and routes, expand transport supply and attract more passengers.

If you integrate the MOTIONTAG SDK inside your own application, you can either download user journeys via a provided dump interface on the internet or we tailor a customized solution to your needs.

This plugin wraps the iOS and the Android SDK on the two platforms respectively.

The general principle was to expose the intersection of the features of the two implementation, meaning that some Android-only and iOS-only features are intentionally left out. Minimum supported OS versions:

Android	iOS
API 23+	iOS 12.3+

1. Installation

First, add motiontag_sdk as a dependency in your pubspec.yaml file.

iOS

The SDK must be initialized before the plugin registration in the didFinishLaunchingWithOptions application's delegate function. The handleEventsForBackgroundURLSession calls must be forwarded by overriding the appropriate delegate. Check out AppDelegate.swift as an example.

Android

Create an Application, which you register in the AndroidManifest.xml.

You have to call MotionTagWrapper.initialize() from the Application's onCreate callback and provide the required arguments. Check out MainApplication.kt as an example.

Auto Backup for Apps is a platform feature that automatically backs up a user's data from apps that target and run on Android 6.0 (API level 23) or later. To limit unexpected behavior from our SDK, you should either disable automated backups entirely or exclude the appropriate SDK files from full backup. Please check this section of the native Android MOTIONTAG SDK for more information.

2. Permission management

Since the permission management is not part of the MOTIONTAG SDK, it is the app's responsibility to acquire the permissions/authorizations from the user before starting the SDK.

The example project demonstrates an implementation using the permission_handler package.

iOS

The SDK requires access to location updates in the background, for that please add following capability in Xcode:

• Capabilities -> Background Modes:
  • Location Updates

Additionally, The SDK requires two authorizations before being started: Location (Always) and Motion. Therefore, add the following items to your app's Info.plist:

• "Privacy - Motion Usage Description" string
• "Privacy - Location Always & When in Use Description" string
• "Privacy - When in Use Description" string

If you use permission_handler make sure to add the requested snippets to the Podfile for each of them.

Android

The following runtime permissions are required before starting the SDK:

• android.permission.ACTIVITY_RECOGNITION
• android.permission.ACCESS_FINE_LOCATION
• android.permission.ACCESS_COARSE_LOCATION
• android.permission.ACCESS_BACKGROUND_LOCATION

Some of these permissions may not be required when targeting older Android versions. Please check the native Android MOTIONTAG SDK documentation for more info.

3. Usage

The MotionTag class is the main entry point of the SDK. It has the following public functions:

Function	Description
Future<void> start() async	Starts tracking. It's not necessary to call this method again after a device reboot.
Future<void> stop() async	Stops tracking.
Future<void> setUserToken(String userToken) async	Sets the user token (JWT). The SDK expects a valid user token prior to executing the start() function. The provided token will be persisted internally.
Future<String?> getUserToken() async	Retrieved the persisted user token or null if it was not previously set.
void setObserver(void Function(MotionTagEvent event)? observer)	Set a function to be called by the SDK to inform abour relevant changes (e.g.: data transmission error, tracking started, etc).
Future<void> clearData() async	Deletes all unstransmitted stored user data from the SDK. This function is useful when signing out the user from your app.
Future<bool> isTrackingActive() async	Returns true if the SDK is currently active, false otherwise.

The MotionTagEvent class is the base class for all notifiable SDK events. The SDK currently supports the following concrete implementations of the MotionTagEvent class:

Event	Description
StartedEvent	Informs the application that tracking has been started.
StoppedEvent	Informs the application that tracking has been stopped.
LocationEvent	Hands the latest captured device location to the application.
TransmissionSuccessEvent	Informs when a package of events has been successfully sent to the server.
TransmissionErrorEvent	Informs when a package of events failed to be transmitted to the server.

4. User authentication

The SDK must be configured at runtime with a user-specific token using JWT. For more information, please check the native Android and/or iOS SDK documentations.

5. Non-standard background process limitations on Android

Some Android OEMs, like Huawei and OnePlus, decided to implement non-standard background process limitations on 3rd party apps as an attempt to reduce battery consumption. The MOTIONTAG SDK must be running all times in the background, otherwise it won't function properly.

Therefore we recommend developers integrating our SDK to read the https://dontkillmyapp.com website, it describes this problem in detail and it provides some workaround options for both developers and users. There's also this StackOverflow post which describes how developers can forward users to the correct OEM settings.

When battery optimization is turned on for your app, the MOTIONTAG SDK may not be able to track and generate data continuously. If 24/7 tracking on all supported phone models is crucial to your use case, we strongly recommend you to include a prompt for the user, and facilitate the deactivation of battery optimization settings for your app on the affected phones.

6. License

The SDK is licensed under the MOTIONTAG SDK Test License.