Menu

Android Analytics Documentation

The MotionTag Mobility Analytics library collects raw sensor data of smartphones. This data is then transmitted to our back-end system. At this place the sensor events are processed and a partial journey is constructed. Journeys consist either solely of tracks or tracks plus stays. Tracks describe a motion from a point of origin to a destination with a certain mode of transport. Stays however, symbolise a stationary behaviour with a particular purpose for the visit.

The collected data enables you to compare how your transport network is being used relative to the transport system as a whole. This way the effectiveness of your current infrastructure and the passenger flow management is measured. Make use of these learnings to improve timetables and routes, expand your offerings and attract more passengers.

If you integrate MotionTag Mobility Analytics library inside your own application, you can either download user journeys via a provided dump interface on the internet or we tailor a customised solution to your needs.

1. Download

1.1 Project build gradle

First you need to add the following to you projects build.gradle file:

allprojects {
    repositories {
        maven {
            url "https://artifactory.motion-tag.de/artifactory/libs-release"
            credentials {
                username = "${ARTIFACTORY_USERNAME}"
                password = "${ARTIFACTORY_PASSWORD}"
            }
       }
   }
}

This allows you to download the library from our custom maven repository.

1.2 Global gradle properties

Additionally you have to add your credentials inside your system’s global gradle.properties file:

ARTIFACTORY_USERNAME = <YOUR_USERNAME>
ARTIFACTORY_PASSWORD = <YOUR_PASSWORD>

On Linux you find this file usually under ~/.gradle/gradle.properties. Please contact us to get your credentials.

1.3 Application build gradle

Lastly, you need to include the following dependency in your application build.gradle file to download the library:

implementation 'de.motiontag:tracker:<VERSION>'

You should be good to go now ;)

2. MotionTag Tracker Structure

2.1 MotionTag.java

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

Returns Method Explanation
void with(Context appContext, Settings settings, MotionTag.Callback callback) Initializes the library with the Application context, Settings and the Callback implementation.
void start(String token) Starts tracking for the specified user JWT token. The provided MotionTag.Callback implementation will be called to inform about SDK state changes or relevant tracking events.
void stop() Stops tracking and removes the foreground notification.
boolean isTrackingActive() Returns true if the tracking is active and collecting data, false otherwise.
void notification(Notification notification) Updates the provided tracking Notification. Can be safely called even after the tracking has been started.
void useBatterySavingMode(boolean on) Enables the Battery Saving Mode, as known as Slow-Mode. In this mode the Location Services is disabled to preserve battery when the phone is stationary after a certain amount of time. Disabling this mode leads to a higher battery usage, however it improves the location tracking. Can be safely called even after the tracking has been started.
void useWifiOnlyDataTransfer(boolean on) Enables the data transmission only when connected to Wifi. Can be safely even called after the tracking has been started.
void turnLoggingOn(boolean on) Activates the SDK logging to see if sensor events are being collected and the data sending process is working as expected. Can be safely called even after the tracking has been started.

2.2 Settings.Builder.java

The Settings class is used to customise the behaviour of the SDK during its initialization. Please refer to section 3.1.

Returns Method Explanation
Settings.Builder notification(Notification notification) Sets the Android Notification to be displayed when tracking is running. The FLAG_ONGOING_EVENT flag will be added to the Notification if not provided. Starting from API version 26 a notification channel must be created first.
Settings.Builder useBatterySavingMode(boolean on) Enables the Battery Saving Mode, so less battery is draining if set to true. In this mode the Location Requests are disabled when stationary to preserve battery. Disabling this mode leads to a higher battery usage, however it improves the location tracking.
Settings.Builder useWifiOnlyDataTransfer(boolean on) Enables Wifi only transmission of sensor events. Disabling this can lead to high cost because of the mobile data usage, however it improves analysis speed, so the user has maybe a faster response of processed journeys.
Settings.Builder turnLoggingOn(boolean on) Activates the logging to see if sensor events are collected or the network requests pass etc.
Settings build() As described in the Builder Pattern a build() method is needed to construct the actual Settings object.

2.3 MotionTag.Callback.java

Callback interface used to inform an application about state changes.

Returns Method Explanation
void onAutoStart(Reason.Start reason) Informs the application that tracking has been automatically started. Please, check the possible reasons on 2.4.1 section.
void onAutoStop(Reason.Stop reason) Informs the application that tracking has been automatically stopped. Please, check the possible reasons on 2.4.2 section.
void onLocation(Location location) Hands the latest captured android.location.Location. to the application.
void onTransmission(long timestamp) Informs when a package of events has been successfully sent to the server. The timestamp parameter represents the time (in milliseconds) of the server confirmation response.

2.4 Reason Class: Reason.java

The Reason class describes the reasons behind the automatic tracking stops and starts. Please check section 4.5 for more information about them.

2.4.1 Reason.Start Enum:

Selection Explanation
RESTART This is the case when tracking is restarted after an application update or a phone restart.
LOCATION_SERVICE This is the case when tracking is restarted after the user turns on the location services.
KILLED This is the case when tracking is restarted after an application kill.

2.4.2 Reason.Stop Enum:

Selection Explanation
RESTART This is the case when tracking is stopped because the application is shutdown.
LOCATION_SERVICE This is the case when tracking is stopped after the user turned off location services.
LOCATION_PERMISSION This is the case when tracking is stopped after the user revoked location permissions for the application.

3. Usage

3.2 Initialization

This initialization should be either in your Application file or in a file that is directly affiliated with the Application, so it’s started/restarted when the Application file is initialized.

class App extends Application {

    private final MotionTag.Callback yourCallback = new CustomClass();
    private Notification yourNotification;

    @Override
    public void onCreate() {
        Settings settings = new Settings.Builder()
                .turnLoggingOn(false)               // default: false
                .useWifiOnlyDataTransfer(true)      // default: true
                .useBatterySavingMode(false)        // default: true
                .notification(yourNotification)     // Your notification that should be shown while tracking is active
                .build();

        MotionTag.with(applicationContext, settings, yourCallback);
    }
}

3.3 Start/Stop Tracking

To start tracking, you need a token for the SDK to access our backend system. Please get in touch and we will provide you with your token as soon as possible.

Using the token you can start…

class CustomClass implements MotionTag.Callback {

    private static final String YOUR_TOKEN = "SECRET_JWT";

    public void start() {
        MotionTag.start(YOUR_TOKEN);
    }
}

… and stop

class CustomClass implements MotionTag.Callback {

    public void stop() {
        MotionTag.stop();
    }
}

… the tracking after the initialization from wherever you want.

3.4 Runtime permissions

The library needs the android.permission.ACCESS_FINE_LOCATION permission, therefore the application must request it from the user before the tracking is started.

3.5 Automatic Start/Stop

When the tracking is ACTIVE it will be automatically stopped and in some cases automatically restarted e.g.

3.6 Callback

You have to implement the MotionTag.Callback to initialize with MotionTag.with(...). The callback informs you about automatic starts and stops as well as about new locations. It can be implemented like…

class CustomClass implements MotionTag.Callback {

    @Override
    public void onLocation(Location location) {
        // do something with the provided location
    }

    @Override
    public void onAutoStart(Reason.Start reason) {
        switch (reason) {
            case RESTART:
                // do something after the tracking was restarted
                // after rebooting the phone or updating the application.
                break;
            case LOCATION_SERVICE:
                // do something after the tracking was restarted
                // by turning on the location services.
                break;
            case KILLED:
                // do something after the application has been killed and
                // the tracking is restarted.
                break;
        }
    }

    @Override
    public void onAutoStop(Reason.Stop reason) {
        switch (reason) {
            case RESTART:
                // do something after the tracking was stopped
                // because the phone was shut down
                break;
            case LOCATION_SERVICE:                
                // do something after the tracking was stopped
                // by turning off the location services.
                break;
            case LOCATION_PERMISSION:
                // do something after the tracking was stopped
                // by revoking the location permissions.
                break;
        }
    }
}

3.7 Runtime Setting Changes

You can still change all settings during runtime. For example if the user changes the language settings on the phone you probably want to provide a new notification with the appropriate language. Just call one of the following methods from anywhere in your application.

class CustomClass implements MotionTag.Callback {

    private Notification yourNotification;

    public void customize() {
        MotionTag.turnLoggingOn(false);
        MotionTag.useWifiOnlyDataTransfer(true);
        MotionTag.useBatterySavingMode(false);
        MotionTag.notification(yourNotification);
    }   
}

4. Phones

4.1 Huawei

Huawei devices have the so called “Protected Apps” mode. Apps not included in this list will be killed by the OS after X minutes counting from the moment the screen is off. Unfortunately, there is no way to programmatically include an app in this list. However, you can inform users about this mode and send them to the “Protected Apps” settings so they can manually add the app there.

String pkg = "com.huawei.systemmanager";
String cls = "com.huawei.systemmanager.optimize.process.ProtectActivity";
ComponentName component = new ComponentName(pkg, cls);
Intent intent = new Intent();
intent.setComponent();

5. Gradle

6. Dependencies

implementation 'com.jakewharton.timber:timber:4.7.0'
implementation 'com.google.dagger:dagger-compiler:2.15'
implementation 'com.google.dagger:dagger:2.15'
implementation 'com.android.support:support-v4:27.1.1'
implementation 'com.android.support:appcompat-v7:27.1.1'
implementation 'com.android.support:support-compat:27.1.1'
implementation 'com.google.android.gms:play-services-location:15.0.1'
implementation 'com.j256.ormlite:ormlite-core:5.1'
implementation 'com.j256.ormlite:ormlite-android:5.1'
implementation 'com.squareup.retrofit2:retrofit:2.4.0'
implementation 'com.squareup.retrofit2:converter-gson:2.4.0'
implementation 'com.squareup.okhttp3:logging-interceptor:3.10.0'
implementation 'com.evernote:android-job:1.2.2'
implementation 'org.greenrobot:eventbus:3.1.1'