100 lines
3.9 KiB
Markdown
100 lines
3.9 KiB
Markdown
# 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:
|
|
```json
|
|
{ "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`:
|
|
```kotlin
|
|
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:
|
|
```bash
|
|
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
|
|
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)
|
|
|
|
```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.
|