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.

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

Official references checked on 2026-08-03:

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