Feature: native background location recording for fitness/move-to-earn mini apps
- Dominant language
- JavaScript
- Stars
- 7
- Forks
- 8
- PR merge metrics
- No merged PRs in 30d
Description
## What
Expose a way for mini apps to record the user's location track while the mini app is **backgrounded / minimized**, then deliver the buffered track when the mini app resumes.
This is a follow-up to #44 (foreground geolocation on iOS). #44 is the prerequisite: without foreground GPS working, this is moot. This issue is specifically about **background** continuity.
## Why it matters
Fitness / move-to-earn / delivery mini apps (running, walking, cycling) need the location track to survive the app being minimized. In a WebView this is impossible from JS alone: the OS freezes the WebView's JavaScript when the host app is backgrounded, so `watchPosition` stops firing and the activity is lost.
Every native fitness app (Strava, Nike Run Club) tracks in background because they hold the OS background-location entitlement. A mini app cannot get that entitlement; only the MiniPay native app can. So MiniPay is the only layer that can solve this for mini apps.
## Concrete example
[MiniKlaim](https://www.miniklaim.fun) is a territory-capture running game. A run must keep tracking distance and capturing map cells while the user has their phone in their pocket with the screen off. Today, minimizing MiniPay (or any in-app browser) pauses tracking entirely and the run stalls.
## Suggested resolution
A custom RPC pair, consistent with the existing `minipay_scanQrCode` / `minipay_requestContact` pattern:
1. `minipay_startLocationRecording({ accuracy, minDistance })` - the **native** MiniPay layer begins recording GPS fixes using its OS background-location capability. Recording continues while the mini app's WebView is frozen.
2. `minipay_stopLocationRecording()` - returns the buffered track as an array of `{ lat, lng, accuracy, timestamp }`.
On resume, the mini app reads the buffered track and processes it (compute distance, claim cells, etc.). Recording happens in native code, so the frozen JS is not a problem.
A simpler v1 could just buffer and replay on resume (no live streaming needed). A streaming variant (`minipay_watchLocation`) could come later for the foreground case and overlaps with #44.
## Notes / constraints we understand
- This needs the iOS background-location entitlement (`UIBackgroundModes: location`) on the MiniPay native app, with App Store justification.
- Battery and privacy: gate it behind an explicit per-session user prompt; only record while a mini app explicitly requested it; auto-stop after N minutes of no foreground return.
- Android has its own foreground-service requirements for background location.
Happy to be a design partner / test device for this - MiniKlaim is a live Celo Proof of Ship app that needs exactly this.
Contributor guide
Research direction
Start by reviewing prerequisite issue #44 and the existing minipay_scanQrCode/minipay_requestContact RPC pattern. Confirm how native iOS and Android background-location requirements fit the proposed start/stop flow, including permission and auto-stop behavior; the work is done when a mini app can retrieve a buffered track after resume while recording continues in the background.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- android, ios, javascript
- Domain
- api, mobile
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100