Menu

Android Analytics Documentation

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 MotionTag Tracker library 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.

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

The SDK requires Java 8 support, therefore is should be added via compileOptions:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

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(Application application, Settings settings, MotionTag.Callback callback) Initializes the library with the Application context, Settings and the MotionTag.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.
void checkIn() Checks in user (e.g., before a public transport trip).
void checkOut() Checks out user (e.g., after a public transport trip).
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.
Settings getSettings() Retrieves current settings
void clearData() Stops tracking and deletes all stored user data from the SDK

2.2 Settings.Builder.java

The Settings class is used to customise the behaviour of the SDK during its initialization.

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. The default is set to true.
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. The default is set to true.
Settings.Builder turnLoggingOn(boolean on) Activates the logging to see if sensor events are collected or the network requests pass etc. The default is set to false.
Settings build() As described in the Builder Pattern a build() method is needed to construct the actual Settings object.

2.3 MotionTag.Callback.java

MotionTag.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.
void onAutoStop(Reason.Stop reason) Informs the application that tracking has been automatically stopped.
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.

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.1 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(application, settings, yourCallback);
    }
}

3.2 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.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 ```Java class CustomClass implements MotionTag.Callback {

public void stop() {
    MotionTag.stop();
} } ``` ... the tracking after the initialization from wherever you want.

3.4 Check In and Check Out

It is possible to check in and check out users (e.g., before a public transport trip). In order to do that tracking must be started first.

To check in…

class CustomClass implements MotionTag.Callback {
    
    private static final String YOUR_TOKEN = "SECRET_JWT";
    
    // Tracking must be active before checking in
    public void start() {
        MotionTag.start(YOUR_TOKEN);
    }
    
    public void checkIn() {
        MotionTag.checkIn();
    }
}

And to check out…

class CustomClass implements MotionTag.Callback {
    
    // Tracking must be active before checking out in
    public void start() {
        MotionTag.start(YOUR_TOKEN);
    }
    
    public void checkOut() {
        MotionTag.checkOut();
    }
}

3.5 Automatic Start/Stop

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

class CustomClass implements MotionTag.Callback {

    @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.6 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);
    }   
}

3.7 Current Settings

You can get current library settings with the following call:

class CustomClass implements MotionTag.Callback {
        
    public Settings getCurrentSettings() {
        return MotionTag.getSettings();
    }   
}

3.8 Clear stored user data

It is possible to delete user data that is stored locally with the following command…

class CustomClass implements MotionTag.Callback {
    
    // more implementation specifics
    
    public void clearUserData() { 
        MotionTag.clearData();
    }
}

Executing this function also stops tracking. This is particularly useful to delete user data when he logs out from the app.

4. Phones

4.1 Huawei/Honor

Huawei and Honor 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

The MotionTag Mobility & Location Analytics SDK relies on Free and Open Source software components. These components are available under the following licenses: