automate toolkit

Documentation of the automate toolkit

View mint-hagenberg on GitHub

More information

The automate toolkit was designed to be easily extensible. Its components were developed as generic as possible to enable a platform independent usage of certain parts for future use. The components of the Android specific implementation can be seen in Figure 3.

automate components
Figure 3. Components of the (Android specific) automate toolkit.

This five components are separated into five repositories (see build @home), with their dependencies depicted in Figure 4.

automate repository dependencies
Figure 4. Dependencies within the automate repositories.

Managers

Managers are used to gather data (e.g. device or interaction information, …) and convert them into different kinds of structured data that can be analysed later. In order to get access to the data, a manager or a couple of them have a corresponding file export handler, which will create structured CSV files from the internal data representation. The following sections go into the details of the managers that are already included in the automate toolkit. The details include a short description as well as data they gather and how the exported data will be structured.
All structured CSV files have a number of general columns (deviceId, sessionId, sequenceNr, projectId and appVersion), which are described in the following.

Field Content type
deviceId String (see ANDROID_ID)
sessionId UUID
sequenceNr Number (unique per session)
projectId UUID (optional)
appVersion Number (see android:versionCode)

App Sequence Manager

Listens for events of app screen visit changes and app interactions (clicks, scrolls, …), and creates a structured XML document out of one session. A session starts when the screen is turned on and the device returns from sleep mode, and it lasts until the device returns to sleep mode again (which usually means the display is off again) or when the device is turned off completely.

Data fetching strategy Event-based
Update frequency Not applicable

XML structure

    <session>
    <appUsage packageName="…" name="…" startTime="…">
    <state name="…" className="…" duration="…" interactionCount="…" orientation="…"/>
    </appUsage>
    </session>
  
The session is just the outer tag to have a single root. Every time an app is opened, there is an appUsage tag with the packageName of the package and the startTime as a timestamp. Inside every appUsage there's a list of state tags which stand for a change in the view (usually Android Activity). They include the name and className of the view if returned by the Android accessibility environment as well as the duration, device orientation and interactionCount in that state.

CSV Export (appsequence.csv)

Field Content type
timestamp Unix timestamp
xml XML string

Widget Interaction Manager

Collects the different interaction events for the current screen. A screen is usually a view like the Android Activity. Interactions are characterized by the interaction type (click, scroll, long click, context click, selected), class name and text, as well as a content description if available. Additional information are the time the interaction occurred as well as the screen bounds of the widget that was interacted on. Due to restrictions on Android, some data can be missing.

Data fetching strategy Event-based
Update frequency Not applicable

CSV Export (appinteraction.csv)

Field Content type
className Text
contentDescription Text
eventTime Unix timestamp
interactionClassName Text
interactionEventTime Unix timestamp
interactionText Text
interactionType Text (Click, Long Click, Selected, …)
orientation Number (compare with Android documentation)
packageName Text
parentBoundsBottom Number
parentBoundsLeft Number
parentBoundsRight Number
parentBoundsTop Number
screenBoundsBottom Number
screenBoundsLeft Number
screenBoundsRight Number
screenBoundsTop Number
title Text
viewIdResourceName Text (compare with Android documentation)

Network Info Manager

This manager waits for changes to the network connection and updates the information accordingly. The relevant data is the network type and subtype that Android reports as well as a flag if the network connection is roaming or not.

Data fetching strategyEvent-based
Update frequencyNot applicable

CSV Export (networkinfo.csv)

Field Content type
duration Length in milliseconds
isRoaming Boolean
startTime Unix timestamp
subType Number (compare with Android documentation)
type Number (compare with Android documentation)

Device Info Manager

Collects the basic device information that rarely changes, like device name and carrier, OS version, resolution, SIM card country and locale.

Data fetching strategyPoll
Update frequencyOn session start

CSV Export (deviceorientation.csv)

Field Content type
date Unix timestamp
device Text
localeCountry Text
localeLanguage Text
location Text
operator Text
OS Text
resolutionHeight Number
resolutionWidth Number
timezoneOffset Number
versionName Text

Battery Info Manager

Whenever the Android battery system manager reports changes to the battery status, this manager compares and updates the stored data, if deemed relevant.

Data fetching strategyEvent-based
Update frequencyNot applicable

CSV Export (batteryinfo.csv)

Field Content type
duration Number
health Number (compare with Android documentation)
isPresent Boolean (compare with Android documentation)
level Number (compare with Android documentation)
plugged Number (compare with Android documentation)
scale Number (compare with Android documentation)
startTime Unix timestamp
status Number (compare with Android documentation)
technology Text (compare with Android documentation)
temperature Number (compare with Android documentation)
voltage Number (compare with Android documentation)

Light Condition Manager

Receives updates from the sensor manager and records changes to the classification of the light condition based on a publication by DisplayMate.

Data fetching strategyEvent-based
Update frequencyDepends on the delay of the sensor manager

CSV Export (lightcondition.csv)

Field Content type
classification Number (according to DisplayMate)
endTime Unix timestamp
startTime Unix timestamp

Orientation Change Manager

Stores the amount of time the device was in one of the possible screen orientations.

Data fetching strategyEvent-based
Update frequencyNot applicable

CSV Export (deviceorientation.csv)

Field Content type
endTime Unix timestamp
orientation Number (compare with Android documentation)
startTime Unix timestamp