# 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
- 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.

## 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.