Set up a CLAID app on Android or WearOS¶

Information on Tutorials 1a, 1b and 1c

Tutorials 1a, 1b, and 1c are meant as alternatives. Choose one based on the type of application you want to create:
         Tutorial 1a: For creating a cross-platform application (works on both Android and iOS).
         Tutorial 1b: For creating an Android/WearOS only application
         Tutorial 1c: For creating an iOS only application.

Welcome to this tutorial on setting up a mobile app using CLAID for Android or WearOS. In this tutorial, we cover how to set up CLAID in an Android or WearOS application created with Android Studio. CLAID for Android and WearOS is installed simply by specifying it as dependency in the build.gradle file.

You can either create a new CLAID application from scratch using one of our templates, or integrate CLAID into an existing application. Check out the options below.

Prerequisite: Using Android Studio

For the following steps you require Android Studio. We assume that you have set up and installed Android Studio and have basic knowledge on how to use it (e.g., how ot open projects). If not, check out the Android Studio beginner tutorials.

Option1: Creating a new CLAID application using a template¶

If you are starting a new application from scratch, it is easiest to simply clone one of our template applications for Android or WearOS respectively.

Cloning the CLAID template application

You can simply clone or download the existing template applications from Github and adapt them as required. CLAID is already configured and ready to use with those applications.

For Android (i.e., smartphones, tablets, ...):

git clone https://github.com/ADAMMA-CDHI-ETH-Zurich/CLAIDAndroidTemplateApp

For WearOS (i.e., smartwatches):

git clone https://github.com/ADAMMA-CDHI-ETH-Zurich/CLAIDWearOSTemplateApp

After you cloned/downloaded the template App, you can open the folder with Android Studio and load the project. If you build and run the application, it looks as follows.

Want to know more?

In case you are interested in how CLAID is integrated into the existing template applications, check out the next section below. The next section covers how CLAID can be integrated into Android/WearOS applications. If you want to know what you now can do with the CLAID App, check out the next tutorial series!

Option2: Integrating CLAID into an existing Android/WearOS application¶

CLAID is available as Android (AAR) package via the maven central repository. Thus, CLAID can simply be added as dependency to existing Android projects. Setting up CLAID for use in an existing application requires three steps:

Adding CLAID as dependency to gradle.
Creating a CLAID configuration file in the assets folder.
Starting CLAID to run in the foreground or background.

Minimum Android SDK Version

CLAID requires a minimum Android SDK Version >= 26.
You might need to change the minumum SDK level of your app.

2.1 Adding CLAID as dependency to gradle¶

To add CLAID as dependency to your Android/WearOS project, you simply have to include it in the dependencies section of the build.gradle file. Check out the instructions below (same for Android/WearOS).

Adding CLAID to the App depdendencies

Open the build.gradle file. Beware, that there are typically two build.gradle files in an Android Studio project. Make sure to open the build.gradle file of the Module. Check the picture below for reference:

Find the dependencies section at the end of the file. Add CLAID using the code below:

dependencies {
    ...
    implementation 'ch.claid:claid:+' // Adds CLAID as dependency.
    ...
}

2.2 Creating a CLAID configuration file in the assets folder.¶

Before we can start CLAID in our App, we need to create a CLAID configuration file. The CLAID configuration file specifies which CLAID Modules to load and how to connect them. The file will be created in the assets folder, so that it is bundled into the application. Check out the instructions below on how to add the assets folder and the configuration file (skip to step 3, if you already have an assets folder).

Adding a CLAID configuration file to assets

1. Create new dirctory2. Specify assets directory path3. Create claid_config.json4. Insert content

Add a new directory to your application by pressing File->New->Directory

Add the folder "src/main/assets" (which is the main assets folder):

Inside the newly created assets folder, create a file called "claid_config.json":

Open the claid_config.json file and paste the following content:

{
    "hosts": [
        {
        "hostname": "Smartphone",
        "isServer": false,
        "modules": []
        }
    ]
}

It should look as follows:

2.3 Starting CLAID to run in the foreground or background¶

On Android/WearOS, you can configure CLAID to run either in the foreground or in the background.

Starting in foreground: Same as for regular applications, the execution of the App is paused when the App moves to the background. Choose this if you only want to use CLAID when the App is open. Not suitable for data collection or continuous tasks.
Start in background: CLAID starts a service and keeps running in the background even if the App is minimized. CLAID implements best practices to keep running in the background as long as possible. Using DeviceOwnerFeatures, CLAID applications are (almost) unkillable. Check out the box at the end of this page for more details. Preferred option for continuous data collection and tasks.

About runtime permissions of CLAID Apps

CLAID automatically handles required permissions for it's Modules, even when it is running in the background. CLAID requests some permissions at startup, and might request additional permissions when more Modules are loaded. In the previously created claid_config, we did not specify any Modules to load, thus CLAID will only ask for a limited number of permissions.

To start CLAID in either the foreground or background, follow the instructions below (mind the tabs to choose between the two alternatives):

Starting CLAID

Starting in the foregroundStarting in the background

To start CLAID in the foreground, you can paste the code below in your MainActivity's or MainApplication's onCreate function.

public class MyApplication extends Application
{
    @Override
    protected void onCreate(Bundle savedInstanceState) 
    {
        super.onCreate(savedInstanceState);
        CLAID.startInForeground(
                getApplicationContext(),
                "assets://claid_config.json", // Path to the previously created config file.
                "Smartphone", // Same as in the config file
                "device", // Device id (optional)
                "user", // User hash (optional, useful for studies)
                // Regular permissions (i.e., no device owner features)
                CLAIDSpecialPermissionsConfig.regularConfig()); 
    }
}

Your MainActivity should look as follows:

To start CLAID in the background, you can paste the code below in your MainActivity's or MainApplication's onCreate function.

public class MyApplication extends Application
{
    @Override
    protected void onCreate(Bundle savedInstanceState) 
    {
        super.onCreate(savedInstanceState);
        CLAID.startInBackground(
                getApplicationContext(),
                "assets://claid_config.json",
                "Smartphone", // Same as in the config file
                "device", // Device id (optional)
                "user", // User hash (optional, useful for studies)
                // Regular permissions (i.e., no device owner features)
                CLAIDSpecialPermissionsConfig.regularConfig(),
                // Keep running as long as possible (App will ask for
                // exemptions from battery restrictions etc.)
                CLAIDPersistanceConfig.maximumPersistance());

    }
}

Your MainActivity should look as follows:

As you can see, when starting CLAID you can specify a CLAIDSpecialPermissionsConfig and a CLAIDPersistanceConfig (only for background). Check out the box below for information about these configs.

What are special permissions and the persistance strategy?

When starting CLAID, you can specify a CLAIDSpecialPermissionsConfig. Additionally, when starting CLAID to run in the background, you can specify a CLAIDPersistanceConfig. These special configuration enable CLAID to use advanced features and be as persistent as possible when running from the background.

Below is a short overview, for details check out the page about CLAID startup options.

CLAIDSpecialPermissionsConfig
Allows CLAID to request special permissions. Options are:

CLAIDSpecialPermissionsConfig.regularConfig(): No special permissions.
CLAIDSpecialPermissionsConfig.allStorageAccessConfig(): Allows CLAID to act as a storage manager, enabling access to the whole userspace file system. This is normally not required, as CLAID apps will store data in the respective App documents directory.
CLAIDSpecialPermissionsConfig.almightyCLAID(): Registers CLAID to act as a device owner, enabling full device management (FDM). FDM Apps can fully control wifi, bluetooth and other modalities completely from the background without user interventions. This is helpful for ensuring that users during a study do not deactivate connectivity, for example. Additionally, FDM apps typically cannot be killed by the user, and can also not be simply uninstalled without using developer tools.

CLAIDPersistanceConfig
Specifies how "aggressive" (persistent) CLAID shall be against termination attempts by the operating system, when running in the background. Options are:

CLAIDPersistanceConfig.minimumPersistance(): CLAID will keep running in the background until either terminated by the operating system, by an exception or when device shut's down. The App will not automatically restart in any of the mentioned cases.
CLAIDPersistanceConfig.maximumPersistance(): The CLAID App will automatically start during device boot. The App will register a watchdog to restart the App within 15 minutes after it has crashed or been terminated. The App will request exemptions from battery optimizations so that the OS is a lot less likely to terminate the App due battery persevation measures.