games_app/docs/MOBILE_APP_RELEASES.md

3.6 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:

  1. Same applicationId (com.prediqo.mobile)
  2. Same signing certificate
  3. 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

  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

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).

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

# 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