Demoing Memfault with the Android Quickstart APK

The Android Quickstart APK is designed to try out the Android SDK quickly and easily without requiring a full installation. It contains a single Android application (APK) that can be sideloaded onto any device that has adb access without requiring modifications to AOSP. It is not designed to be used in production. However, it can still collect much of the data that the full SDK is capable of, including:

• Crashes (Tombstones, Java exceptions, ANRs, WTFs, Last KMSG)
• Metrics
• Log files (up to Android 12)

See Android SDK Features for a full breakdown of which features are available in the Quickstart APK versus the full Android SDK.

Quickstart APK releases are published to the Android Quickstart APK Github repo, on the same cadence as Android SDK releases. See the changelog in the main Android SDK repo.

1. Create a Project

Create or use an existing Memfault Organization. Once you have a Memfault Organization, create a new Android Project for the Quickstart APK.

2. Install the Quickstart APK

i. Enable adb access on your Android device

Ensure that adb is installed - download here if required.

To use adb with a device connected over USB, you need to ensure two settings are enabled on your Android device. Please reference the two links below to set up your device:

• Enable Developer Options
• Enable USB Debugging

ii. Connect the device to your computer

Connect the device to your computer using a USB cable. Verify that your device is connected by executing adb devices from the $ANDROID_SDK/platform-tools/adb directory. Your phone will pop up a banner Allow USB Debugging. Check Always allow from this computer and press Allow.

If properly connected, you'll see the device identifier listed under List of devices attached.

With some additional work, you can also connect to your device over Wi-Fi.

iii. Run the install script

Download bort-lite-release.zip from the master branch of the Android Quickstart APK Github repo (you don't need to check out the repo), and extract to a folder.

On macOS, open the Terminal, and run ./install-bort-lite.sh -k <project-key> -s <device-identifier>, replacing <project-key with the Project Key noted down earlier, and using the optional -s argument to specify a custom device identifier.

On Windows, open the Command Prompt, and run install-bort-lite.bat <project-key>, replacing <project-key with the project key noted down earlier.

Bort is now installed and enabled! Developer mode is ewnabled by default, meaning that all data collected will be uploaded immediately.

3. Collect your first device metrics

The Quickstart APK will continually capture data, and will upload to the Memfault dashboard every 2 hours (when there is connectivity available). So by default, it may take up to 2 hours before seeing the device in the Memfault dashboard.

i. Trigger metrics collection manually

The Quickstart APK will automatically collect metrics immediately after install. These will be visible in the Memfault dashboard, on the Device Timeline.

To collect metrics again:

adb shell am broadcast -a com.memfault.intent.action.REQUEST_METRICS_COLLECTION -n com.memfault.bort.lite/com.memfault.bort.receivers.ShellControlReceiver

Consider enabling Server-Side Developer Mode as well, when using Bort Developer Mode.

Additional Information

The Quickstart APK is released as a single pre-signed binary for convenience — the bort-lite.apk. This is different to how the full Android SDK is released (built from source, signed with your certificate).

The Quickstart APK is limited in what operations it can perform:

• It can only be granted development permissions (i.e. cannot be granted any signature, privileged or system permissions, unless it is also available via developer). Most of the data collected by Bort is available with this permission, but not all.
• It also cannot perform any operations which require a system UID (which would need Usage Reporter, or one of the Bort system services MemfaultStructuredLogD or MemfaultDumpster) or modified SELinux configuration. This includes full access to all sysprops.
• It can not capture Android bug reports or continuous logs (these require a native system service).
• Performing an OTA via Memfault is not possible (this would need both SELinux changes, and system permissions).

The bundled installation script grants all development permissions at install time, using the -g argument to adb install. It also whitelists Bort to run in the background (using dumpsys deviceidle whitelist), without which Bort would not be able to do anything.

See Android SDK Features for a full breakdown of what features are available.