Build @home

In order to build the automate toolkit at home to extend, contribute or simply publish a customized version, you will have to clone the source code from our repositories. Depending on what you want to do, you do not have to clone all repositories, which is why the next section will explain how the source code is split between multiple repositories. The IDE of choice for Android projects is Google's Android Studio with its new gradle-based compile toolchain. At the end of this chapter we will go into the properties which can be used to configure the toolkit without having to modify any source files.

Repositories

The toolkit is split into multiple git repositories hosted on GitHub. They are all prefixed with "automate-", which we will remove in the following in order to make the text easier to read:

Windows Users: Attention when cloning the repositories into already deep directories. Please keep in mind that most Windows versions still limit the length of the path.

The repositories depend on each other as shown in Figure 1.

automate repository dependencies — Figure 1. Dependencies within the automate repositories.

LoggingClientJavaCore

This repository contains the core of the automate toolkit, including the Kernel, which manages both the internal and external managers. Internal managers include the EventManager and DebugLogManager. This repository only depends on Java APIs, which means it can be used as the basis for ports of the automate toolkit on any Java-based platform.

Kernel

The Kernel is responsible for managing the managers as well as their dependencies. As managers can be temporarily dis/enabled during runtime, the Kernel will keep track of installed managers as well as their status. Keeping track of the dis/enabled status between stops/starts of the Kernel is possible. It is not supported out of the box on Java-only platforms though, as the storage possibilities on different systems usually differ.

EventManager

The EventManager is based on the observer pattern and allows the propagation of events throughout the system, which is heavily used in the core system already.

DebugLogManager

The DebugLogManager is used for debug output on the console or elsewhere. It has a simple interface to log text or exception objects using the commonly used classification tags for logging (VEROSE, WARNING, ERROR, …).

LoggingClientAndroidExtension

This repository extends the Java-only LoggingClientJavaCore in order to account for Android specifics. In order to get access to the Context, widely used and required by Android APIs, it includes a specialization of the Kernel - including persisting the dis/enabled state of managers.

In addition the Android extension includes a few useful managers for Android: TrustedTimeManager, CredentialManager and FileExportManager.

TrustedTimeManager

The TrustedTimeManager returns a reliable timestamp from an NTP (Network Time Protokol) server, which is cached and can be refreshed if necessary.

CredentialManager

The CredentialManager keeps track of a user id and session id. The user id is persistent on the filesystem and can be used to track them over mulitple sessions. A session marks the time between the start and stop of the Kernel and the id is re-generated for every new session.

FileExportManager

The FileExportManager can be used to export the stored analytics data from the internal representation onto the filesystem and into CSV files. It uses so called handlers to register for the correct internal data transmission events and serialize the (primitive) objects to the respecitve files.

In order to be able to export data collected by a manager, such a handler has to be implemented. There's not necessarily a 1:1 correspondence between the managers and handlers, as one handler can handle multiple managers at once.

AndroidBaseManager

This repository contains the out-of-the-box managers shipping with the automate toolkit. Check the more page for details on these managers.

AndroidAccessibilityServiceEnvironment

This repository contains an implementation for the Android AccessibilityService, which receives AccessibilityEvents from the Android system and takes care of converting them into internal interaction events (e.g. screen visit and touch interaction).

Additionally, as the AccessibilityService should be running all the time, it will start and stop the Kernel using a BroadcastReceiver for the screen on and off system broadcasts.

AccessibilityRunner

Whereas all the other repositories host libraries, this will build the running Android apk and also includes the final configuration file. This app includes the user interface which lists the managers and allows the user to temporarily dis/enable them. It also includes the RunningNotificationManager, which displays an Android system notification whenever the automate toolkit is running and from which it can be stopped as well.

IDE

We are currently using Android Studio version 2.2.x with the corresponding gradle 2.2.x plug-in.

Configuration

It is possible to configure the toolkit as well as included managers using the Java properties file automate.properties in the Android assets folder of the "main" project. This section will document the properties to configure the automate toolkit in general as well as built-in managers. For details on which (if any) properties the individual tracking managers offer, check the respective documentation for the managers.

FileExportManager

Property	Value type	Default value	Description
fileexport.storeexternal	boolean	false	The file export can optionally use the external storage of the device instead of the private app internal folder to store the gathered data.
fileexport.handler	string list	empty	A list of fully qualified class names for the active file export handler classes.

CredentialManager

Property	Value type	Default value	Description
pro.key	string	empty	Will be used as the project key to differentiate between different projects in e.g. a database.

KernelManagerHelper

Property	Value type	Default value	Description
fileexport.enabled	boolean	false	Indicates if a manager to support the file export should be added to the started/available services.
manager	string list	empty	List of class names of managers that are available and should be started or at least included in the running toolkit.
logging.fileLogging	boolean	empty	Indicates if a file on the external storage should be created for logging the debug output from the developer.

AutomateAccessibilityService

Property	Value type	Default value	Description
accessibility.includeOnly.packageNames	string list	empty	List of package names that should be included by the accessibility service when filtering the events it will generate (empty means no filtering it done).

Checkout steps / what needs to be done to build the automate toolkit

You can checkout every repository you want to work on and open the included project in Android Studio. The build process is the regular gradle process as defined in Android.

As all libraries are included as maven dependencies in gradle, they will be fetched from the remote repository at bintray. If you work on one of these libraries you can publish snapshot versions to you local maven repository (.m2 folder) and include the correct dependencies via gradle. Publishing to local maven is possible using the custom publish{BuildVariant}Local gradle command. Don't forget to add the repository mavenLocal() to the build.gradle when using your own version of the library.