games_app/docs/MOBILE_APP_RELEASES.md

117 lines
4.2 KiB
Markdown

# Mobile app releases (Android APK)
Tloto can distribute Android APK updates from its own infrastructure without Google Play.
## Architecture
- **Admin web**: Options → Mobile versions (`/admin/mobile-versions`)
- **API public**: `GET /api/v1/app-updates/android`, download + events
- **API admin**: `/api/v1/admin/mobile-releases*`
- **Storage**: Docker volume `apk_releases` → `/app/data/apk-releases/{staging|published}`
- **Flutter**: checks at splash + resume, downloads APK, verifies SHA-256, opens system installer
## Prerequisites — Android signing
Upgrades replace the installed app **only if**:
1. Same `applicationId` (`com.prediqo.mobile`)
2. Same signing certificate
3. Higher `versionCode`
### Create a release keystore (once)
```bash
keytool -genkey -v -keystore tloto-release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias tloto
```
Store the `.jks` **offline** (password manager / encrypted backup). Never commit it or leave it only on the VPS.
### Wire Flutter release signing
1. Copy `prediqo_mobile/android/key.properties.example` → `key.properties`
2. Fill `storePassword`, `keyPassword`, `keyAlias`, `storeFile`
3. Build release APK (production API URL is the default in release mode):
```bash
flutter build apk --release
# or pin explicitly:
flutter build apk --release --dart-define-from-file=dart_defines.prod.example.json
```
The public website header exposes an Android download icon that calls `GET /api/v1/app-updates/android/latest` (only works once a release is **published**).
### Fingerprint for the backend
```bash
keytool -list -v -keystore tloto-release.jks -alias tloto
# Copy SHA-256 certificate fingerprint (hex), strip colons
```
Set in `.env` / Compose:
```env
ANDROID_APK_EXPECTED_CERT_SHA256=<hex without colons>
ANDROID_APK_EXPECTED_PACKAGE=com.prediqo.mobile
```
Empty fingerprint skips cert check (dev only).
The API reads the signing cert from APK Signature Scheme **v2/v3** (and JAR v1 when present). Modern Flutter release APKs often have no `META-INF/*.RSA`.
## Admin publish flow
1. Create a release (version name + **versionCode** strictly greater than the current published one)
2. Upload the signed `.apk`
3. Backend validates package name, versionCode, optional cert fingerprint, computes file SHA-256
4. Submit → Publish
5. Optionally set rollout % (5 / 20 / 50 / 100) and update policy (optional / recommended / mandatory)
### Suspend / rollback
- **Suspend** or **retire** stops offering that APK to new checks
- Devices that already installed it **cannot** be downgraded; ship a higher `versionCode` hotfix instead
## Mobile client behaviour
- Compares installed `buildNumber` (versionCode) to server
- Policies:
- optional / recommended → dismissible dialog
- mandatory (or below `min_supported_version_code`) → blocking dialog; sensitive APIs return **426**
- Download uses the **same host as `API_BASE_URL`** (path `/api/v1/app-updates/android/download/...`), not `APP_PUBLIC_URL` — avoids slow/failing hits on a different HTTPS port
- HMAC token; size + SHA-256 verified before install; screen kept awake during download
- Android system installer prompt is never bypassed
## Backup & VPS migration
```bash
# List volumes
docker volume ls | grep apk
# Backup APK volume
docker run --rm -v <project>_apk_releases:/data -v "$(pwd)":/backup alpine \
tar czf /backup/apk_releases.tgz -C /data .
# Restore on new host then recreate stack with the same volume name
```
Also dump PostgreSQL tables `mobile_app_releases`, `mobile_app_release_events`, `mobile_app_update_settings`.
`storage_key` values are relative (`published/<uuid>.apk`) so the mobile `downloadUrl` contract stays API-driven if you later move blobs to object storage.
## iOS
Architecture reserves `platform=ios` but **does not** distribute IPA files. Future: App Store / TestFlight links only.
## Manual test checklist
- [ ] Detect new version (versionCode +1)
- [ ] Optional update — Later still uses the app
- [ ] Recommended update messaging
- [ ] Mandatory update blocks bets / withdraw (426)
- [ ] Interrupted download / bad network
- [ ] Corrupted APK / wrong SHA-256 rejected
- [ ] Wrong signing cert rejected on upload
- [ ] User cancels Android installer
- [ ] Local session retained after successful update
- [ ] Suspended release no longer offered