who_need_help/android/play-store/location-and-fgs-declaration.md

# Google Play location and foreground-service declaration

This file is the source copy for Play Console. It describes the exact current
Android behavior; it is not evidence that Google Play has approved the feature.
Reconcile every answer with the AAB selected for release.

## Manifest and permission facts

- Package: `org.whoneedhelp.mobile`
- Target SDK: `37`
- Foreground service type: `location`
- Foreground-service permissions: `FOREGROUND_SERVICE` and
  `FOREGROUND_SERVICE_LOCATION`
- Runtime location permissions: `ACCESS_COARSE_LOCATION` and
  `ACCESS_FINE_LOCATION`
- The app does not request `ACCESS_BACKGROUND_LOCATION`.
- The app also declares `USE_LOCATION_BUTTON` for the separate one-time
  foreground action that places a request or activity point. It must not use
  `onlyForLocationButton`, because the distinct live-location flow also needs
  precise location after the user starts the foreground service.

## Foreground-service declaration copy

**Use case:** User-initiated location sharing.

**Feature using the service:**

> During an active mutual-aid assignment, an accepted requester or helper can
> explicitly start live location sharing with the matched participant. Who Need
> Help starts a location foreground service only after the user opens the active
> assignment, taps Share live location, reads the prominent disclosure, and
> grants Android location permission. A persistent notification remains visible
> for the full session and includes a Stop sharing action.

**Why the task must start immediately:**

> The participant starts sharing to coordinate an active, time-sensitive handoff.
> Deferring the first update would show the matched participant stale or missing
> position information at the moment the user deliberately requested sharing.

**Impact if Android interrupts the task:**

> New location updates stop. The app does not silently restart sharing. The user
> must return to the active assignment and start it again. The matched participant
> no longer receives a current position.

**How it ends:**

- The user taps Stop sharing in the app or in the persistent notification.
- Cancelling, withdrawing from, completing, or otherwise leaving the active
  assignment stops the native service through the server-driven terminal state.
- The service also stops on an authorization or missing-assignment response.
- Stopping removes the current raw location from the server. Limited derived
  safety evidence can remain as stated in the Privacy Policy.
- Sharing is never started from boot, a background receiver, a push notification,
  or an unattended scheduled task.

## Play Console answers

Use these only when the current Console wording matches the stated fact:

- Foreground service type: **Location**
- Closest preset use case: **Background Location Updates — User-initiated
  location sharing**
- Core user benefit: safe coordination between the two people already matched
  for an active help request
- Persistent notification: shown after the explicit in-app start and prominent
  disclosure, with a user-visible Stop action
- Background-location runtime permission declared: **No**
- Location foreground service declared: **Yes**

Google Play requires a foreground-service declaration for apps targeting
Android 14 or newer. Do not describe this feature as passive, continuous,
always-on, emergency, medical, or hidden tracking.

## Video evidence script

Record one short, unlisted video from the exact Play candidate. Keep the phone
screen readable and show the complete trigger path without cuts that hide a
permission or disclosure screen.

1. Start on an active synthetic request in which the signed-in reviewer is an
   accepted requester or helper.
2. Scroll to live-location controls and tap **Share live location**.
3. Pause on the prominent disclosure long enough to read what is collected,
   who receives it, minimized-app use, deletion, and the Stop action.
4. Tap **Continue and share** and grant the Android location permission.
5. Show the persistent **Sharing live location** system notification.
6. Press Home so the app is minimized; show that the notification remains
   visible and that the matched browser receives a current synthetic position.
7. Tap **Stop sharing** in the notification.
8. Return to the request and show that sharing is stopped and the live marker is
   no longer available.

Do not use a real home address, real medical information, chat text, email,
handover code, access token, or another person's location in the recording.

### Current draft review

The local 30-second draft
`/g/home/Downloads/Who-Need-Help-Play-Console-location-sharing-DRAFT.mp4`
was visually reviewed on 2026-08-09. Its SHA-256 is
`550d831747e75abb4ad1bea11ff20c37b6ceedbf971883643d102fd04168b2ab`.
It shows the before-sharing state, the in-app trigger, prominent disclosure,
Android location permission, active in-app state, persistent notification,
the matched participant's live marker, background/minimized operation, the
notification Stop action, and the removed marker after Stop.

This draft is a recording reference, not final Play submission evidence. The
final unlisted video must be recorded from the exact `0.1.2 (3)` build delivered
through Google Play Internal testing, and that installed build must pass the
Play installer, signing identity, App Link, active-sharing, and Stop-cleanup
checks before the video URL is entered in Play Console.

### Reproducible production fixture

The production operator script creates one run-scoped requester with a temporary
password, one synthetic matched medicine request, and one accepted assignment
for an existing confirmed helper. It refuses any root, Compose project, public
origin, image, health state, or database other than the explicitly verified
production values. It stores the exact IDs and temporary credentials only in
ignored mode-`0600` runtime files so cleanup can be resumed after a container
restart.

Run the read-only plan first from `/srv/who_need_help-production`:

```bash
./scripts/production-play-physical-fixture.sh \
  plan HELPER_EMAIL --check-only whoneedhelp.com .env
```

Prepare the recording fixture only when the helper is signed into the exact
Play-delivered build:

```bash
./scripts/production-play-physical-fixture.sh \
  prepare HELPER_EMAIL --confirm whoneedhelp.com .env
```

Use the printed temporary requester email and password in the recipient browser.
Do not copy those credentials into documentation, Play Console, chat, email, or
the recording. After location sharing starts, verify the server-side active
state; after using the notification Stop action, verify deletion:

```bash
./scripts/production-play-physical-fixture.sh \
  verify-active --confirm whoneedhelp.com .env

./scripts/production-play-physical-fixture.sh \
  verify-stopped --confirm whoneedhelp.com .env
```

Always remove the fixture immediately after the recording, including after an
aborted take:

```bash
./scripts/production-play-physical-fixture.sh \
  cleanup --confirm whoneedhelp.com .env
```

Cleanup stops an exact still-active fixture session before deleting its current
raw position, tracking session, messages, notifications/jobs, assignment,
request, temporary tokens/rate-limit buckets, and requester. It then verifies
that the three primary fixture records were deleted and removes the local
runtime state. Never delete the runtime manifest manually while its fixture may
still exist.

## Pre-submission evidence

- Run `./scripts/android-play-policy-check.sh`.
- Run the signed release build and retain its manifest/package/signing reports.
- Repeat start, Home/minimize, notification, Stop, and raw-position deletion on
  a Play-delivered internal-test install after Play App Signing is available.
- Confirm the Privacy Policy, Data Safety form, store listing, disclosure, and
  Play Console declaration all describe the same behavior.

Foreground-service references rechecked on 2026-08-09:

- https://support.google.com/googleplay/android-developer/answer/13392821
- https://developer.android.com/develop/background-work/services/fgs/service-types

The Play Help page was rechecked again on 2026-08-10. It still requires a video
link for each declared foreground-service feature and recommends keeping the
demonstration at 30 seconds or less. The final edit must therefore retain the
user trigger, prominent disclosure, runtime prompt, minimized persistent
notification, and notification Stop action while removing only idle time.

### Play-delivered evidence take on 2026-08-10

The exact Play-delivered `0.1.2 (3)` build produced a long evidence take at:

`/g/home/Downloads/Who-Need-Help-Play-Console-location-sharing-FINAL-v4.mp4`

Its SHA-256 is
`56608ca3e2e1aafd7a85c325109581c379d4cb714794ba4c6c414706d451ff96`.
The file is 177.864689 seconds, H.264, and 720×1600. Visual review confirms the
in-app trigger, prominent disclosure, Android runtime prompt, active in-app
state, Home/minimized operation, and persistent notification with the visible
Stop action. It contains no account email, fixture credentials, precise map,
medical information, chat, or handover code.

This take is retained only as source evidence. The recorder reached its time
limit before the notification Stop tap and stopped in-app state were captured,
so it must not be submitted to Play Console as the final demonstration. The
Stop action was performed immediately afterward: server verification observed
41 samples and zero retained raw positions, and exact fixture cleanup passed.
A new concise take must visibly include Stop and the stopped state.

### Final Play-delivered demonstration

The final concise demonstration was recorded on 2026-08-10 from the exact
Google Play Internal-testing install `0.1.2 (3)` and saved as:

`output/android/play-console/wnh-fgs-review-final-v5.mp4`

It is 21.379802 seconds, H.264, 720×1600, and its SHA-256 is
`3c5f52019bf8a42ff42e1d9232afc126b62627390d74eed75084d82ecb33ac56`.
Visual review confirms that it shows the in-app trigger and prominent
disclosure, Android location prompt, active sharing state, minimized-app
persistent notification, visible notification Stop action, and the returned
stopped state with **Share location** available again. It contains no account
email, fixture credentials, precise map, medical information, chat, or handover
code.

Server-side verification for the same take observed active tracking with a
retained current position, then stopped tracking with zero retained raw
positions. Exact cleanup deleted the run-scoped request, assignment, tracking
session, and temporary requester; the protected runtime state and prepare log
were removed. Production readiness remained healthy. This file is final local
evidence, but it is not considered submitted until an unlisted hosted URL is
entered and saved in Play Console.

The remaining Play policy references were rechecked on 2026-08-10. The current
Play Help still requires a video demonstration for the declared permission and
accepts a YouTube link (preferred) or a cloud-hosted common video file. It also
states that an unresolved declaration for an active bundle can prevent
publishing other changes, including Store Presence. Refresh the pages again
immediately before submitting because Play Help can change independently of
the Android platform documentation:

- https://support.google.com/googleplay/android-developer/answer/9799150
- https://support.google.com/googleplay/android-developer/answer/16909972
- https://support.google.com/googleplay/android-developer/answer/9214102