aw-android

A very work-in-progress ActivityWatch app for Android.

Available on Google Play:

Usage

Install the APK from the Play Store or from the GitHub releases.

For Oculus Quest

Note At some point a Quest system upgrade broke the ability to allow ActivityWatch access to usage stats. This can be fixed by manually assigning the needed permission using adb: adb shell appops set net.activitywatch.android android:get_usage_stats allow

It's available on SideQuest.

Building

To build this app you first need to build aw-server-rust (./aw-server-rust) and aw-webui (./aw-server-rust/aw-webui).

If you haven't already, initialize the submodules with: git submodule update --init --recursive

Building aw-server-rust

Note If you don't want to go through the hassle of getting Rust up and running, you can download the jniLibs from aw-server-rust CI artifacts and place them in mobile/src/main/jniLibs manually instead of following this section.

To build aw-server-rust you need to have Rust nightly installed (with rustup). Then you can build it with:

export ANDROID_NDK_HOME=`pwd`/aw-server-rust/NDK  # The path to your NDK
pushd aw-server-rust && ./install-ndk.sh; popd    # This configures the NDK for use with Rust, and installs the NDK if missing
env RELEASE=false make aw-server-rust             # Set RELEASE=true to build in release mode (slower build, harder to debug)

Note The Android NDK will be downloaded by install-ndk.sh to aw-server-rust/NDK if ANDROID_NDK_HOME not set. You can create a symlink pointing to the real location if you already have it elsewhere (such as /opt/android-ndk/ on Arch Linux).

Building aw-webui

To build aw-webui you need a recent version of node/npm installed. You can then build it with make aw-webui.

Putting it all together

Once both aw-server-rust and aw-webui is built, you can build the Android app as any other Android app using Android Studio.

Making a release

Use the Release workflow to bump the version, commit it, and create the tag in one atomic step. This ensures the committed versionName matches the tag (required for F-Droid, which builds from tagged source).

1. Go to Actions → Release → Run workflow
2. Enter the version number (e.g. 0.12.2, without the v prefix)
3. Click Run workflow

The workflow will:

• Update versionName in mobile/build.gradle
• Commit the change to master
• Create and push tag v{version}
• Trigger the Build workflow (requires a RELEASE_PAT secret — a GitHub PAT with repo scope)

This will trigger a GitHub Actions workflow which will build the app and upload it to GitHub releases, and deploy it to the Play Store (including the metadata in ./fastlane/metadata/android).

Note for maintainers: Add a RELEASE_PAT secret (repo-scoped GitHub PAT) so the tag push from the Release workflow triggers the Build workflow. Without it, the Build workflow must be triggered manually after the tag is pushed.

Research builds

A tag with a -research suffix (e.g. v0.14.2b1-research) is a study build: it builds and publishes to GitHub releases only and is never pushed to the Play Store. scripts/assert-play-track.sh resolves any -research tag to the none track and the release-fastlane job skips it (fail-closed, so a case-variant like -Research is also refused).

• versionName: the -research suffix is a distribution-channel marker, not a version component, so the Build workflow's versionName assertion strips it from both the tag and the committed versionName before comparing (scripts/strip-research-suffix.sh). A research tag v0.14.2b1-research is verified against the committed 0.14.2b1 — and a Release-workflow run with a -research input (which commits the suffixed versionName) also passes. The reverse is refused: a plain tag whose committed versionName carries -research fails the assertion, so a research-marked build can never reach Play production from a plain tag. Self-test: scripts/strip-research-suffix.sh --self-test.
• F-Droid: aw-android is not currently in F-Droid's fdroiddata, so there is no F-Droid version regex that could attempt to build a -research tag. If the app is ever added to F-Droid, the maintainer must ensure its version regex ignores -research tags (F-Droid builds from tagged source).
• Signing: a study needs one stable signing key for its duration so participants can install updates over the top of a sideloaded APK. Note that a future Play release may be re-signed by Play App Signing, which would break in-place upgrades for sideloaded installs — acceptable for a pilot that ends, but it should be planned for before any long-lived sideloaded distribution.

More info

For more info, check out the main ActivityWatch repo.