104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
# Who Need Help for Android
|
|
|
|
This module is a native Android WebView shell for the Phoenix application. It
|
|
keeps authentication cookies, LiveView WebSockets, MapLibre, and chat in the
|
|
same trusted origin. Live location is sent by a user-started native foreground
|
|
service with a persistent notification and Stop action, so it can continue
|
|
while the Activity is minimized without requesting Android's
|
|
background-location permission.
|
|
|
|
## Verified build configuration
|
|
|
|
- Android Gradle Plugin 9.3.0
|
|
- Gradle 9.6.1
|
|
- Android SDK Command-line Tools 22.0
|
|
- Android CLI 1.0.15857036 (embedded in the locked Command-line Tools archive)
|
|
- compileSdk / targetSdk 37
|
|
- Build Tools 37.0.0
|
|
- Java source and bytecode level 17
|
|
- minSdk 24 (project baseline, not an Android SDK requirement)
|
|
|
|
The debug origin is not stored in the Dockerfile or Gradle project. Set
|
|
`WNH_DEBUG_BASE_URL` in the repository's ignored `.env` file. The supplied
|
|
local configuration uses loopback together with `adb reverse`; debug builds
|
|
allow cleartext traffic, while the WebView still restricts in-app navigation to
|
|
that one configured origin.
|
|
|
|
The same ignored file supplies `WNH_TRACKING_MIN_TIME_MS` and
|
|
`WNH_TRACKING_HTTP_TIMEOUT_MS`. The checked-in example preserves the original
|
|
local client freshness and timeout behavior; these values are not claimed as
|
|
measured production capacity settings.
|
|
|
|
Release builds do not have a default server. Supply the real HTTPS deployment:
|
|
|
|
```sh
|
|
./gradlew :app:assembleRelease \
|
|
-PWNH_BASE_URL=https://help.your-domain.example \
|
|
-PWNH_TRACKING_MIN_TIME_MS=5000 \
|
|
-PWNH_TRACKING_HTTP_TIMEOUT_MS=15000
|
|
```
|
|
|
|
The build rejects a missing, HTTP, credentialed, query-bearing, or
|
|
fragment-bearing release URL.
|
|
|
|
## Public staging build
|
|
|
|
The installable `staging` build type uses the explicit public HTTPS
|
|
`WNH_BASE_URL`, disables cleartext traffic, and has its own
|
|
`org.whoneedhelp.mobile.staging` application ID. Configure a missing local value
|
|
from the existing `PHX_HOST`, `PHX_SCHEME`, and `PHX_URL_PORT`, then build:
|
|
|
|
```sh
|
|
./scripts/ensure-local-public-origin.sh
|
|
./scripts/android-staging-build.sh
|
|
sha256sum android/dist-staging/who-need-help-staging.apk
|
|
```
|
|
|
|
This variant uses Android's generic debug signing key so it can be installed
|
|
for staging verification. It is not a production-signed artifact and must not
|
|
be published as a release. The manifest accepts same-origin HTTPS deep links,
|
|
but verified Android App Links additionally require the final signing
|
|
certificate fingerprint in the deployment's `/.well-known/assetlinks.json`.
|
|
|
|
## Reproducible Docker build
|
|
|
|
From the repository root:
|
|
|
|
```sh
|
|
./scripts/android-build.sh
|
|
sha256sum android/dist/who-need-help-debug.apk
|
|
```
|
|
|
|
The Docker build runs JVM unit tests, Android lint, and `assembleDebug` before it
|
|
exports the APK and lint report.
|
|
|
|
## Emulator verification
|
|
|
|
The optional `emulator` target contains the API 37.0 Google APIs x86_64 system
|
|
image. It requires KVM and host networking. Pass the same `.env` value as a
|
|
build argument, then expose the Compose proxy to Android with `adb reverse`:
|
|
|
|
```sh
|
|
set -a
|
|
. ./.env
|
|
set +a
|
|
docker build \
|
|
--build-arg "WNH_DEBUG_BASE_URL=$WNH_DEBUG_BASE_URL" \
|
|
--build-arg "WNH_TRACKING_MIN_TIME_MS=$WNH_TRACKING_MIN_TIME_MS" \
|
|
--build-arg "WNH_TRACKING_HTTP_TIMEOUT_MS=$WNH_TRACKING_HTTP_TIMEOUT_MS" \
|
|
--target emulator \
|
|
-t who-need-help-android:emulator \
|
|
android
|
|
docker run --rm --name who-need-help-android-emulator \
|
|
--device /dev/kvm \
|
|
--network host \
|
|
who-need-help-android:emulator
|
|
docker exec who-need-help-android-emulator adb reverse tcp:4010 tcp:4010
|
|
docker exec who-need-help-android-emulator adb install \
|
|
/opt/who-need-help/who-need-help-debug.apk
|
|
```
|
|
|
|
The application ID `org.whoneedhelp.mobile` is provisional until the publishing
|
|
identity and store listing are chosen. Changing it after publication creates a
|
|
different Android application.
|