KwabaTV/docs/superpowers/specs/2026-09-27-in-app-updates-design.md

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.