Add in-app updates design spec
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LHgWjmEJXsJEi1EVAoTp4K
This commit is contained in:
Claude Sonnet 5
@@ -0,0 +1,158 @@
|
||||
# In-App Updates — Design
|
||||
|
||||
Date: 2026-09-27
|
||||
Status: approved, pending implementation plan
|
||||
|
||||
## Background
|
||||
|
||||
KwabaTV has no update mechanism today — every new build requires a manual
|
||||
`adb install -r` sideload from a development machine. That's fine for this
|
||||
session's iteration pace, but not sustainable once the app is "done" and
|
||||
just sitting on a Fire TV Stick: any future fix requires physically
|
||||
reconnecting ADB.
|
||||
|
||||
Kwaba Sync's own desktop Electron app (`desktop/`, in the `kwaba-sync`
|
||||
repo) already solved an equivalent problem: the server proxies the latest
|
||||
GitHub-style release from Gitea (`src/desktop-release.js`), gated behind a
|
||||
login because that repository is private, and the Electron app polls it,
|
||||
shows an in-window update banner, and never installs without an explicit
|
||||
click.
|
||||
|
||||
KwabaTV's own Gitea repo (`GGB/KwabaTV`) is public — confirmed via its
|
||||
Gitea API (`visibility":"public"`, releases endpoint returns 200
|
||||
unauthenticated). That removes the reason the desktop app's design needed a
|
||||
server-side proxy at all (private-repo auth). This design is intentionally
|
||||
simpler than desktop's as a result: no `kwaba-sync` involvement, no
|
||||
server-side changes, no coordination needed with that repo's owner. It
|
||||
mirrors desktop's *behavior* (check on launch, never install silently,
|
||||
graceful failure) without mirroring its *architecture*.
|
||||
|
||||
## Goal
|
||||
|
||||
The app checks Gitea for a newer release on every launch, and — if one
|
||||
exists — offers to download and install it, entirely on-device.
|
||||
|
||||
## Release convention
|
||||
|
||||
- `versionName` in `app/build.gradle.kts` moves from the current `"1.0"`
|
||||
to a proper 3-part semver (e.g. `"1.1.0"`) as part of this work, since
|
||||
the comparison logic below assumes major/minor/patch on both sides.
|
||||
- Tag format: `vX.Y.Z` (e.g. `v1.1.0`), matching `versionName`.
|
||||
- Exactly one APK asset per release, always named `KwabaTV.apk`, so the
|
||||
app never has to guess which asset to download.
|
||||
- Releases are published manually for now (no CI in this repo yet).
|
||||
Drafts and pre-releases are ignored by the version check.
|
||||
|
||||
## Components
|
||||
|
||||
All new code lives in kwabatv; nothing else changes outside it.
|
||||
|
||||
**`UpdateChecker.kt`** — a small, self-contained class with one entry
|
||||
point, e.g. `checkForUpdate(context, onAvailable: (UpdateInfo) -> Unit)`.
|
||||
On a background thread, it does a plain HTTP GET to
|
||||
`https://git.whodovoodoo.de/api/v1/repos/GGB/KwabaTV/releases`, picks the
|
||||
highest-versioned non-draft, non-prerelease release whose tag matches
|
||||
`vX.Y.Z`, and compares it numerically (major/minor/patch) against
|
||||
`BuildConfig.VERSION_NAME`. If the release is newer, it calls back with
|
||||
`{ version, apkDownloadUrl }` on the main thread. Any failure along the
|
||||
way (network unreachable, non-200, malformed JSON, no matching release) is
|
||||
swallowed silently — no error UI, no retry logic beyond "try again next
|
||||
launch."
|
||||
|
||||
**`MainActivity.onCreate()`** calls `UpdateChecker.checkForUpdate(...)`
|
||||
right after `webView.loadUrl(BuildConfig.WEBSITE_URL)`, so the check never
|
||||
delays getting to content. If the callback fires, it shows a native
|
||||
`AlertDialog`:
|
||||
|
||||
> **KwabaTV v1.1.0 ist verfügbar**
|
||||
> [Aktualisieren] [Später]
|
||||
|
||||
Android's default dialog buttons are focusable and DPAD-navigable with no
|
||||
extra work. "Später" just dismisses; the same check runs again next
|
||||
launch, with no persisted "skip this version" state.
|
||||
|
||||
**Download + install**, triggered by "Aktualisieren":
|
||||
|
||||
- Uses `android.app.DownloadManager` (a base-SDK system service — no
|
||||
AndroidX needed, keeping the app's existing zero-dependency footprint)
|
||||
to download the APK asset directly from Gitea's public release URL.
|
||||
- Registers a `BroadcastReceiver` for
|
||||
`DownloadManager.ACTION_DOWNLOAD_COMPLETE` to know when the download
|
||||
finishes.
|
||||
- On completion, calls `DownloadManager.getUriForDownloadedFile(id)` — this
|
||||
returns a ready-to-use `content://` URI with no custom `FileProvider`
|
||||
setup required (the earlier draft of this design needed one, which
|
||||
would have pulled in an AndroidX dependency; `DownloadManager` avoids
|
||||
that entirely).
|
||||
- Fires `Intent(ACTION_VIEW)` with that URI, MIME type
|
||||
`application/vnd.android.package-archive`, and
|
||||
`FLAG_GRANT_READ_URI_PERMISSION`, which opens Android's own system
|
||||
package installer. The user taps "Install" themselves inside that
|
||||
system UI — Android does not allow silent unattended installs, by OS
|
||||
design, regardless of permissions granted.
|
||||
|
||||
**First-run permission gate:** before firing the install intent, check
|
||||
`packageManager.canRequestPackageInstalls()`. If false (first time ever
|
||||
installing an update), send the user to
|
||||
`Settings.ACTION_MANAGE_UNKNOWN_APP_SOURCES` for this package instead, so
|
||||
they can grant "install unknown apps" for KwabaTV specifically. They then
|
||||
press "Aktualisieren" again to retry.
|
||||
|
||||
**New manifest entries:**
|
||||
- `<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />`
|
||||
- No new `<provider>` entry (avoided by using `DownloadManager`, see
|
||||
above).
|
||||
|
||||
## Data flow
|
||||
|
||||
```
|
||||
App launch
|
||||
→ webView.loadUrl(WEBSITE_URL) [not blocked by the check]
|
||||
→ UpdateChecker (background thread)
|
||||
GET git.whodovoodoo.de/.../releases
|
||||
→ newer release found?
|
||||
no → nothing happens
|
||||
yes → AlertDialog on main thread
|
||||
"Später" → nothing further this launch
|
||||
"Aktualisieren" → canRequestPackageInstalls()?
|
||||
no → Settings.ACTION_MANAGE_UNKNOWN_APP_SOURCES
|
||||
yes → DownloadManager.enqueue(apk)
|
||||
→ ACTION_DOWNLOAD_COMPLETE
|
||||
→ ACTION_VIEW install intent
|
||||
→ system installer UI (user taps Install)
|
||||
```
|
||||
|
||||
## Error handling
|
||||
|
||||
Every failure mode in the check itself (DNS/network failure, non-200,
|
||||
malformed JSON, no releases, no tag matching `vX.Y.Z`) results in no
|
||||
dialog and no visible change — identical to a launch where the app is
|
||||
already current. This matches desktop's graceful-degradation philosophy:
|
||||
an update check is a nice-to-have, never something that should be able to
|
||||
block or degrade normal app use.
|
||||
|
||||
Download failures (`DownloadManager` reports a failed status) are also
|
||||
silent for now — the user can just press "Aktualisieren" again next
|
||||
launch, or manually sideload as a fallback (this doesn't remove that
|
||||
option). A visible failure toast is a reasonable future improvement, not
|
||||
required for the first version of this feature.
|
||||
|
||||
## Testing
|
||||
|
||||
This feature cannot be meaningfully unit-tested in isolation — the
|
||||
interesting behavior is entirely about real network calls, real Android
|
||||
permission state, and the real system package installer. It will be
|
||||
verified end-to-end on the real Fire TV Stick used throughout this
|
||||
project: publish an actual test release on the `GGB/KwabaTV` Gitea repo,
|
||||
then run the full check → dialog → download → permission-gate →
|
||||
install flow on-device, the same hands-on verification approach used for
|
||||
every other feature this session.
|
||||
|
||||
## Out of scope (for this pass)
|
||||
|
||||
- Any `kwaba-sync` server changes (Option B from the design discussion —
|
||||
hosting the APK for discovery from the Kwaba website's lobby — is a
|
||||
separate, later concern, not required for in-app updates to work).
|
||||
- CI/automated release publishing.
|
||||
- Periodic re-checks while the app stays open (check is launch-only).
|
||||
- "Skip this version" / persisted dismissal state.
|
||||
Reference in New Issue
Block a user