4.2 KiB
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:
- Same
applicationId(com.prediqo.mobile) - Same signing certificate
- Higher
versionCode
Create a release keystore (once)
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
- Copy
prediqo_mobile/android/key.properties.example→key.properties - Fill
storePassword,keyPassword,keyAlias,storeFile - Build release APK (production API URL is the default in release mode):
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
keytool -list -v -keystore tloto-release.jks -alias tloto
# Copy SHA-256 certificate fingerprint (hex), strip colons
Set in .env / Compose:
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
- Create a release (version name + versionCode strictly greater than the current published one)
- Upload the signed
.apk - Backend validates package name, versionCode, optional cert fingerprint, computes file SHA-256
- Submit → Publish
- 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
versionCodehotfix 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/...), notAPP_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
# 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