motiontag_sdk

Description:

motiontag sdk

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.