celo-org / celo-org/minipay

Feature: native background location recording for fitness/move-to-earn mini apps

Open
#46 3 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.