# 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= 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 / delete - **Suspend** or **retire** stops offering that APK to new checks (file and DB row remain) - **Delete permanently** (`DELETE /admin/mobile-releases/:id`) removes the APK file on disk, FIM snapshot, related telemetry events, and the DB row - Devices that already installed a deleted/retired build **keep the app** (Android cannot downgrade); ship a higher `versionCode` hotfix instead - You **cannot** delete the current highest **published** release for that platform/channel — publish a newer build first, or suspend/retire it - Prefer deleting older duplicates (same `versionName`, lower `versionCode`) after a newer published build exists ## 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 _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/.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