Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions .github/workflows/release-shimmercapture.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,14 @@
# build reads the version; fails if it is already tagged, if versionCode did not go up since the
# last ShimmerCapture release, or if the app is not set to PUBLIC; lists the PRs since
# that release in the run summary, to write whats_new from; builds the signed release
# APK. Read-only (no keystore without it): it also runs, unsigned, on PRs.
# APK, shrunk and obfuscated by R8, and keeps R8's mapping.txt as its own artifact.
# Read-only (no keystore without it): it also runs, unsigned, on PRs.
# release tags ShimmerCapture_v<version> on the commit it built and creates the GitHub
# pre-release with the APK and notes since the previous ShimmerCapture release.
# Pre-release, so the Android API release stays "Latest", as before.
# play google_play only: uploads the same APK to Play's Production track as a draft.
# play google_play only: uploads the same APK to Play's Production track as a draft, with
# mapping.txt so Play's crash reports show the real class and method names. The
# mapping is never attached to the public GitHub release.
#
# If a later job fails, "Re-run failed jobs" re-runs just that job.
#
Expand Down Expand Up @@ -327,6 +330,14 @@ jobs:
path: release-assets/
if-no-files-found: error

# R8's map from obfuscated names back to the code, for Play's crash reports. Its own artifact,
# so the release job, which publishes everything in shimmercapture-apk, never makes it public.
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: shimmercapture-mapping
path: ShimmerAndroidInstrumentDriver/shimmerServiceExample/build/outputs/mapping/release/mapping.txt
if-no-files-found: error

release:
needs: build
if: github.event_name == 'workflow_dispatch' && !inputs.dry_run
Expand Down Expand Up @@ -383,6 +394,11 @@ jobs:
name: shimmercapture-apk
path: release-assets

- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
name: shimmercapture-mapping
path: release-mapping

- name: Write the release notes
working-directory: .
env:
Expand All @@ -408,6 +424,7 @@ jobs:
serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON }}
packageName: com.shimmersensing.shimmerconnect
releaseFiles: release-assets/${{ needs.build.outputs.apk }}
mappingFile: release-mapping/mapping.txt
releaseName: ${{ needs.build.outputs.version }}
track: production
status: draft
Expand Down
4 changes: 4 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@ Android API workflow; it dry-runs on any PR that changes it. `release-shimmercap
same for the ShimmerCapture app (`shimmerServiceExample`): a signed APK, a GitHub pre-release and a
draft Google Play release. Its version comes from that module's `build.gradle`, so each release
starts with an uprev PR; `shimmerServiceExample/RELEASING.md` is the step-by-step guide.
ShimmerCapture's release build runs R8 (DEV-1426): all `com.shimmerresearch` code is kept as it
is, because it relies on serialization and reflection, and only the third-party libraries are
shrunk and obfuscated. Anything new found by name needs a rule in its `proguard-rules.pro`, and the
debug build, which R8 never touches, does not show what it breaks.

## Modules

Expand Down
41 changes: 38 additions & 3 deletions ShimmerAndroidInstrumentDriver/shimmerServiceExample/RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@ release anything else.
Then, as before the workflow existed:

1. Sync Gradle in Android Studio, **Clean Project**, run the app on a device and check that it
connects, configures, streams and plots.
connects, configures, streams and plots. That is the debug build, which R8 does not touch:
the release build must be checked too, from a dry run (step 2, and *R8* below).
2. Commit (`ShimmerCapture 1.3.4 (versionCode 35)`), push, and open a PR into `master`.
3. Wait for CI ("Build and test") to pass, get it reviewed, and merge.

Expand Down Expand Up @@ -73,7 +74,9 @@ A dry run does everything up to the signed APK and stops. Open the run to check:
it. Do not choose any option on *Protected with Play* → *Manage Play app signing* as part of a
release: enrolling cannot be undone.
- The APK itself is on the run page under **Artifacts** (`shimmercapture-apk`), to install on a test
device.
device. It is the release build, shrunk and obfuscated by R8 exactly as it will ship, so this is
the APK to test on hardware before a release (see *R8* below). Uninstall the Play version first:
a debug or Play install of the app is signed differently and blocks installing it over the top.

A dry run can be started from any branch, so it is also the way to try an uprev before merging it.

Expand Down Expand Up @@ -149,6 +152,36 @@ Not uploading through the workflow? Download the APK from the GitHub release, an
- Move the ticket on in Jira.
- If the release changes what the app does, update this module's [README](README.md).

## R8: shrinking and obfuscation

The release build runs R8 (`minifyEnabled true`), which Google Play expects: without it Play Console
flags *DEX code optimisation is below our threshold*. R8 removes code it thinks is unused and renames
the rest. The rules in [`proguard-rules.pro`](proguard-rules.pro) say what it must leave alone, each
with its reason:

- **All Shimmer code** (`com.shimmerresearch.**`: the driver, this library, the app and the
biophysical processing jar) is kept as it is, because it uses Java serialization and reflection
that R8 cannot see. Only the third-party libraries are shrunk and obfuscated; they are about 80%
of the app's classes, well past Play's 25%.
- **androidplot** and **AndroidBluetoothLibrary**, which work by reflection.
- **Two AppCompat names** `MainActivity` reaches by name to align the toolbar.
- `-dontwarn` for classes the driver refers to but the app never had (protobuf, Netty, JNA,
desktop UI): R8 only reports them.

What R8 breaks, it breaks **at runtime, not at build time**: a class or field found by name is
missing, and the app crashes (`ClassNotFoundException`, `NoSuchFieldException`) or, worse, quietly
behaves differently. The debug build is never shrunk, so it cannot show this. Before each release,
install the dry run's APK and check on hardware what the app does: connect, configure, stream and
plot, SD logging, CSV, and the Verisense functions, on a Shimmer3, a Shimmer3R and a Verisense over
Bluetooth Classic and BLE.

When something new is reached by reflection or serialization, add a `-keep` rule for it with a
comment saying why. When a crash report from Play shows obfuscated names, it was uploaded without a
mapping: the play job uploads R8's `mapping.txt` with each release (it is kept as the
`shimmercapture-mapping` artifact, never on the public GitHub release). For a release built by hand,
upload `shimmerServiceExample/build/outputs/mapping/release/mapping.txt` in Play Console → *App
bundle explorer* → the version → *Downloads* → *ReTrace mapping file*.

## When a run fails

**Re-run failed jobs** on the run page re-runs only what failed, so a GitHub release that was
Expand All @@ -163,6 +196,8 @@ already created is not created twice.
| `No SHIMMERCAPTURE_KEYSTORE_BASE64 secret` | The signing secrets are missing. See *Secrets* below |
| `The APK is not signed with the ShimmerCapture release key` | The keystore secret holds a different key from the one Play knows. Nothing was published. Replace `SHIMMERCAPTURE_KEYSTORE_BASE64` (and its passwords and alias) with the original keystore, see *Secrets* below |
| `The APK does not carry versionName …` | The build didn't pick up `build.gradle`'s values. Check for a version override in Gradle files |
| `Missing classes detected while running R8` | A dependency now refers to a class the app doesn't have. If the code that refers to it can't run in ShimmerCapture, add a `-dontwarn` for it to `proguard-rules.pro`, with the reason, as for protobuf and Netty. If it can run, the class is needed: add the dependency |
| The released app crashes, or misbehaves, where the debug build doesn't | R8 removed or renamed something found by name. Find it from the crash report (Play maps the names back) and add a `-keep` rule |
| **play**: `No GOOGLE_PLAY_SERVICE_ACCOUNT_JSON secret` | The Play secret is missing. The GitHub release is done; upload by hand (step 4), or add the secret and re-run the job |
| **play**: `The caller does not have permission` | The service account lacks access to ShimmerCapture in Play Console, or was just added: new permissions can take a day. Re-run the play job later |
| **play**: `APK specifies a version code that has already been used` | That `versionCode` reached Play before, e.g. by hand. Uprev again |
Expand Down Expand Up @@ -202,4 +237,4 @@ Get-Content -Raw <key.json> | gh secret set GOOGLE_PLAY_SERVICE_ACCOUNT_JSON --r
If the workflow is unavailable, Android Studio still does the same job: **Build** → **Generate
Signed App Bundle / APK** → **APK** → module `shimmerServiceExample`, the upload keystore, build
variant **release**. The APK lands in `shimmerServiceExample/release/`. Do the uprev (step 1) first
all the same, then upload as in step 4.
all the same, then upload as in step 4, with R8's `mapping.txt` (see *R8* above).
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,19 @@ android {
applicationId "com.shimmersensing.shimmerconnect"
minSdkVersion 21
targetSdkVersion 36
versionCode 37
versionName "1.3.4"
versionCode 38
versionName "1.3.5"
multiDexEnabled true

testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"

}
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
// R8 shrinks, optimises and obfuscates the release build. Google Play flags apps
// without it (DEV-1426). What must not be touched is kept in proguard-rules.pro.
minifyEnabled true
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
}
}
configurations.all {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,25 +1,76 @@
# Add project specific ProGuard rules here.
# By default, the flags in this file are appended to flags specified
# in C:\Users\Jos\AppData\Local\Android\Sdk/tools/proguard/proguard-android.txt
# You can edit the include path and order by changing the proguardFiles
# directive in build.gradle.
# R8 rules for ShimmerCapture's release build (DEV-1426).
#
# For more details, see
# http://developer.android.com/guide/developing/tools/proguard.html
# Google Play flags apps whose code R8 does not optimise or obfuscate. R8 shrinks,
# optimises and obfuscates everything except what is kept here: the third-party
# libraries (AndroidX, Material, Guava, FastBle, ...) are most of the app, and
# they need no rules of their own.
#
# What is kept, and why. Each is code R8 cannot see being used, so it would
# remove or rename it and break the app only at runtime, not at build time.

# Shimmer code: the driver (shimmerdriver, shimmerbluetoothmanager), this repo's
# library, the app, and the closed-source ShimmerBiophysicalProcessingLibrary jar.
# - Java serialization: device objects are cloned through ObjectOutputStream
# (e.g. configuring a device works on a clone), and many classes have private
# readObject/writeObject, which only serialization calls.
# - Reflection: ExGConfigBytesDetails.getExGConfigOptionFields() and
# UartPacketDetails.getUartPropertyParsed() collect static fields by
# reflection, so R8 would drop those fields as unused.
# Keeping it whole means that is safe without auditing each class. Optimising it
# is left for later, with a test on hardware for each change.
-keep class com.shimmerresearch.** { *; }
-keep interface com.shimmerresearch.** { *; }

# androidplot: its Configurator sets plot properties from XML by reflecting on
# getter and setter names.
-keep class com.androidplot.** { *; }

# AndroidBluetoothLibrary: built around reflection.
-keep class it.gerdavax.** { *; }

# Add any project specific keep options here:
# MainActivity aligns the toolbar by reaching into AppCompat by name: it reads
# Toolbar's private mTitleTextView by reflection, and finds the overflow menu by
# its class's simple name, "ActionMenuView". R8 would rename both, and the code
# fails silently (the title and the menu icon just lose their alignment).
-keepclassmembers class androidx.appcompat.widget.Toolbar {
android.widget.TextView mTitleTextView;
}
-keepnames class androidx.appcompat.widget.ActionMenuView

# If your project uses WebView with JS, uncomment the following
# and specify the fully qualified class name to the JavaScript interface
# class:
#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
# public *;
#}
# Serialization of the non-Shimmer classes a device object holds, e.g. Guava
# collections: keep what Java serialization uses but R8 cannot see.
-keepclassmembers class * implements java.io.Serializable {
static final long serialVersionUID;
private static final java.io.ObjectStreamField[] serialPersistentFields;
!static !transient <fields>;
private void writeObject(java.io.ObjectOutputStream);
private void readObject(java.io.ObjectInputStream);
java.lang.Object writeReplace();
java.lang.Object readResolve();
}

# Uncomment this to preserve the line number information for
# debugging stack traces.
#-keepattributes SourceFile,LineNumberTable
# Classes the driver refers to that are not in the app, and were not before R8
# either: R8 only reports the references. They are reached only by driver code
# ShimmerCapture does not run (gRPC, Shimmer4, desktop UI), which is kept as-is
# above, so the app fails no differently than it did.
# - excluded on purpose in the root build.gradle (exclude group: ...)
-dontwarn com.google.protobuf.**
-dontwarn io.netty.**
-dontwarn com.sun.jna.**
# - desktop-only (the driver also runs on PCs)
-dontwarn java.awt.**
-dontwarn javax.swing.**
# - optional dependencies of gRPC, Netty and Guava
-dontwarn org.eclipse.jetty.alpn.**
-dontwarn org.eclipse.jetty.npn.**
-dontwarn org.apache.log4j.**
-dontwarn org.apache.logging.log4j.**
-dontwarn org.slf4j.impl.**
-dontwarn org.jetbrains.annotations.**
-dontwarn reactor.blockhound.**
-dontwarn sun.misc.**

# If you keep the line number information, uncomment this to
# hide the original source file name.
#-renamesourcefileattribute SourceFile
# Line numbers in Play's crash reports. Play maps the rest back with the
# mapping.txt the release workflow uploads.
-keepattributes SourceFile,LineNumberTable
-renamesourcefileattribute SourceFile
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,20 @@
import android.app.ProgressDialog;
import android.content.DialogInterface;
import android.content.pm.PackageManager;
import android.graphics.Color;
import android.net.Uri;
import android.os.Looper;
import android.os.Message;

import androidx.activity.EdgeToEdge;
import androidx.activity.SystemBarStyle;
import androidx.annotation.NonNull;
import androidx.appcompat.widget.Toolbar;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;
import androidx.core.graphics.Insets;
import androidx.core.graphics.drawable.DrawableCompat;
import androidx.core.view.ViewCompat;
import androidx.core.view.WindowCompat;
import androidx.core.view.WindowInsetsCompat;
import androidx.fragment.app.FragmentManager;

Expand Down Expand Up @@ -194,7 +196,10 @@ public void requestPermissions(){
startServiceandBTManager();
}

WindowCompat.setDecorFitsSystemWindows(getWindow(), false);
// Edge to edge, as Android 15+ enforces for apps targeting it, the way Google Play
// recommends (DEV-1426). Status bar icons stay light: the toolbar behind them is dark in
// both light and dark mode. The insets listeners below keep content clear of the bars.
EdgeToEdge.enable(this, SystemBarStyle.dark(Color.TRANSPARENT));
setContentView(R.layout.activity_main);

Toolbar toolbar = findViewById(R.id.toolbar);
Expand Down
Loading