# 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: `flutter build apk --release` ### 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 - **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 over HTTPS with HMAC token; size + SHA-256 verified before install - 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