M2-04: Location opt-in and the permission prompt #31

New issue

Closed

opened 2026-08-08 19:56:52 -04:00 by agent · 0 comments

agent commented

2026-08-08 19:56:52 -04:00

Member

A Settings toggle that turns location capture on, and the entitlement prompt behind it.

Wes: "GPS tracking as an opt-in setting. Prompt for the location entitlement, collect only while
recording a memo."

Why this is its own issue

Nothing is collected until this is on, so it lands before anything that collects. It is also the
whole privacy surface of the feature in one screen, which makes it worth reviewing on its own
rather than buried in the change that starts a CLLocationManager.

The authorization decision

Decided 2026-08-08: "When In Use", with background location updates.

allowsBackgroundLocationUpdates on a When-In-Use authorization is what keeps points arriving
while the phone is locked and Stash is in the background — which is every recording that matters,
because roughly all of them happen on a walk. It requires location in UIBackgroundModes
alongside the audio mode already there.

The accepted cost: the blue location indicator will sit on the lock screen next to the Live
Activity for the whole recording. "Always" authorization avoids the indicator and was rejected
as asking for far more than a voice memo needs — Stash has no reason to know where the phone is
when it is not recording.

Scope

A toggle in Settings, off by default.
Turning it on requests When-In-Use authorization.
Denied, restricted and "reduced accuracy" each say what they are and what it means, with a route
to Settings. A toggle that reads as on while iOS is refusing is the failure to avoid.
Turning it off stops collection for subsequent recordings and does not touch tracks already on
disk.
The screen says plainly what is collected and when: coordinates while a recording runs, nothing
otherwise, written to a .gpx beside the memo and never sent anywhere — there is no sync until
M3, and the relay is blind by design when it arrives.
This copy is shared with M2-10's explainer, which offers the same opt-in from the heat map's
empty state. One string source used in both places: two descriptions of a privacy behaviour is
how they drift, and the one nobody updates is the one somebody reads.

Not in this

No collection, no writing, no map. The toggle sets a preference and holds the authorization; the
next two issues use it.

Done when

The toggle is off on a fresh install and no location prompt has appeared.
Turning it on prompts, and granting it leaves the toggle on.
Denying at the system prompt leaves the toggle off and says why.
Revoking the permission in iOS Settings while the app is backgrounded is reflected on return.

Milestone 2 of the Stash v3 rebuild. M2 is still app-side — no sync, no account, no server. It
turns a list of memos into something you can open, listen to, read and see the route of. Sync
arrives in M3. There is no milestone/M2 label yet (creating org labels needs owner rights), so
the title carries the milestone.

Working agreement for every issue in this repo: feature branch, tested before the PR opens
(on-device where the label says so), then Wes reviews the PR and we walk the code together. Docs
update in the same commit. A PR that takes more than 20 minutes to review is too big — say so and
split it.

A Settings toggle that turns location capture on, and the entitlement prompt behind it. Wes: *"GPS tracking as an opt-in setting. Prompt for the location entitlement, collect **only while recording a memo**."* ## Why this is its own issue Nothing is collected until this is on, so it lands before anything that collects. It is also the whole privacy surface of the feature in one screen, which makes it worth reviewing on its own rather than buried in the change that starts a `CLLocationManager`. ## The authorization decision **Decided 2026-08-08: "When In Use", with background location updates.** `allowsBackgroundLocationUpdates` on a When-In-Use authorization is what keeps points arriving while the phone is locked and Stash is in the background — which is every recording that matters, because roughly all of them happen on a walk. It requires `location` in `UIBackgroundModes` alongside the `audio` mode already there. The accepted cost: **the blue location indicator will sit on the lock screen next to the Live Activity for the whole recording.** "Always" authorization avoids the indicator and was rejected as asking for far more than a voice memo needs — Stash has no reason to know where the phone is when it is not recording. ## Scope - A toggle in Settings, **off by default**. - Turning it on requests When-In-Use authorization. - Denied, restricted and "reduced accuracy" each say what they are and what it means, with a route to Settings. A toggle that reads as on while iOS is refusing is the failure to avoid. - Turning it off stops collection for subsequent recordings and does not touch tracks already on disk. - The screen says plainly what is collected and when: coordinates while a recording runs, nothing otherwise, written to a `.gpx` beside the memo and never sent anywhere — there is no sync until M3, and the relay is blind by design when it arrives. - **This copy is shared with M2-10's explainer**, which offers the same opt-in from the heat map's empty state. One string source used in both places: two descriptions of a privacy behaviour is how they drift, and the one nobody updates is the one somebody reads. ## Not in this No collection, no writing, no map. The toggle sets a preference and holds the authorization; the next two issues use it. ## Done when - [ ] The toggle is off on a fresh install and no location prompt has appeared. - [ ] Turning it on prompts, and granting it leaves the toggle on. - [ ] Denying at the system prompt leaves the toggle off and says why. - [ ] Revoking the permission in iOS Settings while the app is backgrounded is reflected on return. --- *Milestone 2 of the Stash v3 rebuild. M2 is still app-side — **no sync, no account, no server**. It turns a list of memos into something you can open, listen to, read and see the route of. Sync arrives in M3. There is no `milestone/M2` label yet (creating org labels needs owner rights), so the title carries the milestone.* *Working agreement for every issue in this repo: feature branch, tested before the PR opens (on-device where the label says so), then Wes reviews the PR and we walk the code together. Docs update in the same commit. A PR that takes more than 20 minutes to review is too big — say so and split it.*

agent added the

labels

2026-08-08 19:56:52 -04:00

agent referenced this issue from a pull request that will close it,

2026-08-09 17:28:08 -04:00

M2-04: Location opt-in and the permission prompt #45