timebank-cc-public/references/ANDROID_APP_UPDATE_FLOW.md

Android App Update Flow

Overview

The app checks for updates itself via the App settings dialog. When a newer version is available, the user can download and install it directly from within the app. No Play Store is involved.

Key Files

File	Role
app/Http/Controllers/AppVersionController.php	Serves /app/version JSON with current versionCode, versionName, and apkUrl
storage/app/public/apk/timebank-cc-{version}.apk	APK served to users
scripts/deploy-apk.sh	Uploads APK to server and patches the version controller
AndroidStudioProjects/Timebankcc/app/build.gradle.kts	Android version numbers

How the In-App Update Check Works

1. User opens App settings → Check for updates
2. App fetches https://timebank.cc/app/version — returns:

   { "versionCode": 4, "versionName": "1.0.2", "apkUrl": "https://timebank.cc/storage/apk/timebank-cc-1.0.2.apk" }
   

3. If serverVersionCode > BuildConfig.VERSION_CODE, the Download and install button appears
4. User taps it — the APK is downloaded to the app's internal cache dir and the system installer is launched
5. Android asks the user to confirm installation (REQUEST_INSTALL_PACKAGES permission required)

Release Process

Step 1 — Bump version in Android Studio

In app/build.gradle.kts:

versionCode = 5        // increment by 1 each release
versionName = "1.0.3"  // semantic version shown to users

Step 2 — Build a signed APK

Build → Generate Signed Bundle / APK → APK → release

Output: app/release/app-release.apk

Step 3 — Copy to local storage folder

Rename and place in the local APK folder:

cp ~/AndroidStudioProjects/Timebankcc/app/release/app-release.apk \
   storage/app/public/apk/timebank-cc-1.0.3.apk

The filename must follow the pattern timebank-cc-{versionName}.apk.

Step 4 — Deploy to server

bash scripts/deploy-apk.sh

The script:

• Picks the most recently modified timebank-cc-*.apk from storage/app/public/apk/
• Derives versionName from the filename
• Auto-increments versionCode if the version name has changed
• SCPs the APK to /var/www/timebank_cc/storage/app/public/apk/ on the server
• Patches $versionCode and $versionName in AppVersionController.php on both the server and locally

Version Number Rules

• versionCode — integer, must increase with every release. The app compares this to decide whether an update is available. The deploy script increments it automatically.
• versionName — human-readable string shown in the App settings dialog (e.g. 1.0.3). Derive the APK filename from this.

APK Storage

• Local: storage/app/public/apk/ (symlinked to public/storage/apk/)
• Remote: /var/www/timebank_cc/storage/app/public/apk/
• Public URL: https://timebank.cc/storage/apk/timebank-cc-{versionName}.apk

Old APK files can be kept or deleted — only the filename referenced by AppVersionController is served to users.

Permissions Required (AndroidManifest.xml)

<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />

This allows the app to launch the system installer for the downloaded APK.

Troubleshooting

"Download failed — please try again"

• Check that the APK filename in AppVersionController.php exactly matches the file in storage/app/public/apk/
• Verify the file is publicly accessible: curl -I https://timebank.cc/storage/apk/timebank-cc-{version}.apk
• APK is saved to cacheDir (internal) — no storage permission needed

Update not offered to users

• Confirm versionCode on the server is higher than the versionCode baked into the installed APK (BuildConfig.VERSION_CODE)
• Check /app/version response: curl https://timebank.cc/app/version

Users not seeing the update without checking manually

• By design — the check is manual via App settings. There is no background polling.