feat(android): raise minSdkVersion to 30 (Android 11) + document requirements (#77)

Raise the Android APK floor from API 24 (Android 7.0) to API 30 (Android 11).
minSdkVersion is the OS-level install gate, so Android refuses to install the
APK on versions below the floor -- no runtime check needed. Chosen for OS
security hardening + AOSP patch availability (pre-11 is off Google's monthly
Security Bulletins) and our tested range (emulator 11->latest, vivo 1907 /
Android 12). Reach: ~86.9% of active devices (was 96.6% at API 24).

- tauri.conf.json: minSdkVersion 24->30; version 3.8.0->3.9.0
- Cargo.toml + about.ts: version -> 3.9.0 (kept aligned, gotcha #18)
- webapp/TAURI.md: "Why Android 11" rationale + sources + tested devices
- README.md / README.vi.md: Android note 7.0/API24 -> 11/API30
- docs/pc_spec.md (+ vi): Android (Tauri APK) tested-devices table
- CHANGELOG.md: add [3.9.0]; backfill the missing [3.8.0] entry
- CLAUDE.md: gotcha #19 (minSdk floor rationale + reach table) + current state

Sources: endoflife.date/android, source.android.com Security Bulletins,
StatCounter version share (May 2026), apilevels.com (Apr 2026).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 4.8 authored and GitHub committed 2026-06-15 20:51:54 +07:00
1 parent ac466a3042
commit 316f258ba6
10 files changed
+137 -12

No files matched your search

+67
View File
@@ -2,6 +2,73 @@
All notable changes to this project will be documented here.
## [3.9.0] - 2026-06-15 (Android minSdk → 11 / API 30)
### Changed
- **Android APK floor raised from API 24 (Android 7.0) to API 30 (Android 11).**
`minSdkVersion` in [`webapp/src-tauri/tauri.conf.json`](webapp/src-tauri/tauri.conf.json)
`bundle.android` is now `30`. Because Android's package installer refuses any APK whose
`minSdkVersion` exceeds the device API level, this **is** the install block — the app simply
can't install on Android < 11 ("app not installed / incompatible"); no runtime check by design.
Rationale, stated honestly:
- **Not a JS-feature floor** — the System WebView is independently updatable down to API 24, so
SubtleCrypto / OpenPGP.js / IndexedDB / ES2020 already work on older OSes. That's not the
binding constraint.
- **Security + patch availability** — Android 11 added scoped-storage enforcement, one-time /
auto-reset permissions, and a tighter sandbox; pre-11 releases are also off Google's AOSP
monthly Security Bulletins (Android 10 ended 2023-03-06, Android 11 ended 2024-02-05; only
14 / 15 / 16 remain as of mid-2026).
- **Tested range** — we validate only on Android 11+ (emulator 11 → latest; real phone
vivo 1907 / Android 12 — see [`docs/pc_spec.md`](docs/pc_spec.md)). Shipping an untested floor
was the real risk.
- **Reach cost is small** — API 30+ ≈ 86.9% of active devices (was 96.6% at API 24); only the
pre-2020 long tail is dropped.
Data sources: [endoflife.date/android](https://endoflife.date/android),
[Android Security Bulletins](https://source.android.com/docs/security/bulletin),
[StatCounter version share](https://gs.statcounter.com/android-version-market-share/mobile/worldwide/) (May 2026),
[apilevels.com](https://apilevels.com/) (StatCounter cumulative distribution, Apr 2026).
### Notes
- `versionCode` re-derives to `3009000` (gotcha #18). The web and desktop builds are unaffected by
the Android floor. The `about.ts` version bump busts the IndexedDB catalog cache (harmless).
## [3.8.0] - 2026-06-15 (Android APK target 📱)
### Added
- **Android APK build & packaging via Tauri mobile.** The same React + Tauri app now ships as a
sideloadable **arm64-v8a `.apk`** (no Play Store), built and **post-signed** (`zipalign` →
`apksigner`) by [`.github/workflows/release_android.yml`](.github/workflows/release_android.yml)
and attached to the same draft Release as the desktop installers (manual `workflow_dispatch`
uploads it as a downloadable workflow artifact instead). `gen/android` stays gitignored — signing
is a post-build step, not a Gradle edit. New repo secrets: `ANDROID_KEYSTORE_BASE64` /
`ANDROID_KEYSTORE_PASSWORD` / `ANDROID_KEY_ALIAS`. Full build/signing docs in
[`webapp/TAURI.md`](webapp/TAURI.md).
- **Mobile UX** — the Android hardware / gesture back button is wired to in-app router history
(`useBackButton`), safe-area insets are respected, and the sidebar shows a platform-aware badge
("Mobile app" / "Desktop app").
- Added dependency: `@tauri-apps/api`.
### Changed
- **Bundle `identifier` is now alphanumeric** — `com.poli0981.freegamesitchio` (was the hyphenated
`com.poli0981.free-games-itchio-webapp`). Android rejects hyphens in the app id (`android init`
panics) and Tauri's validator rejects underscores, so alphanumeric is the only form valid on
both. Tauri uses one identifier across all platforms, so this also changed the **desktop** bundle
ID (a one-time OS-level reinstall).
- **Realigned versions** — `tauri.conf.json` / `Cargo.toml` / `about.ts` set to `3.8.0` (was a
long-standing `0.1.1` vs `3.x` drift), so `versionCode` / `versionName` are sensible and
monotonic.
### Notes
- CI: the Android JDK setup must **not** use `cache: gradle` — `gen/android` is gitignored and
generated mid-job, so there are no gradle files at checkout to key on (it hard-fails). rust-cache
+ npm cache still apply.
## [3.7.1] - 2026-06-14 (Hotfix — desktop build vs invalid Tauri NSIS license key)
### Fixed
+3 -2
View File
@@ -114,6 +114,7 @@ Fine-grained PAT scoped to **only this repo** with:
16. **The bundle `identifier` must be alphanumeric (no `-`, no `_`).** Android rejects hyphens in the app id (`tauri android init` panics — `NotAsciiAlphanumeric`), while Tauri's own config validator rejects underscores. The only form valid on *both* is alphanumeric segments — ours is `com.poli0981.freegamesitchio` (changed from the old hyphenated `com.poli0981.free-games-itchio-webapp` in v3.8.0). Tauri uses ONE identifier across all platforms, so this also changed the desktop bundle ID (one-time OS-level reinstall). The macOS `.pkg` `pkgbuild --identifier` in `release_desktop.yml` reads it from `tauri.conf.json` so it can't drift.
17. **Android signing: `zipalign` BEFORE `apksigner`.** `gen/android` is gitignored + regenerated by `android init`, so we never edit the generated Gradle — `release_android.yml` builds an *unsigned* APK and post-signs it. Re-aligning a *signed* APK invalidates the signature, so the order is zipalign → apksigner → verify. Pin the CI NDK to match local. Never lose the signing keystore (Android needs a stable signing identity to upgrade an installed APK in place).
18. **Android `versionCode`/`versionName` derive from `tauri.conf.json` version** (`versionCode = major*1e6 + minor*1e3 + patch`). Keep `tauri.conf.json` + `Cargo.toml` versions aligned with the real release line (was a long-standing `0.1.1` vs `3.x` drift — fixed to `3.8.0` in v3.8.0) so the code is sensible and monotonic.
19. **Android `minSdkVersion` is the install gate — change it only in `tauri.conf.json`.** It's **30 (Android 11)** as of v3.9.0 (was 24). Lives in `bundle.android.minSdkVersion`; Tauri injects it into the gitignored generated Gradle on `android init`, so that's the *only* place to set the floor (don't edit `gen/`). Android's package installer refuses any APK whose `minSdkVersion` exceeds the device API level, so **raising `minSdkVersion` IS the "block install on unsupported Android" mechanism** — there is intentionally **no runtime OS-version check** (redundant, and would need `@tauri-apps/plugin-os`). The floor is **not** a JS-feature limit (the System WebView is updatable down to API 24); it's chosen for OS-level security hardening + patch availability (pre-11 is off Google's AOSP Security Bulletins) and our tested range (emulator 11→latest, vivo 1907 / Android 12 — see `docs/pc_spec.md`). Reach trade-off (StatCounter, mid-2026): API 24 ≈ 96.6%, **API 30 ≈ 86.9%**, API 31 ≈ 78.8%, API 33 ≈ 68.9%, API 34 ≈ 54.5%. Don't chase API 34 (Google's oldest still-supported version) — too aggressive for sideloaded reach.
## Safe-edit rules
@@ -122,6 +123,6 @@ Fine-grained PAT scoped to **only this repo** with:
- Don't commit a real PAT, ever. Settings page handles it client-side; CI uses `secrets.GH_TOKEN`.
- When adding an npm dep, also add it to `webapp/src/lib/about.ts` so the About page lists it.
## Current state (as of v3.8.0)
## Current state (as of v3.9.0)
`main` is the trunk. Tags `v3.0.0` through `v3.8.0` exist (all GPG-signed); the webapp is published at `https://poli0981.github.io/free-games-itchio-list/app/`. v3.7.0 added the first-launch legal-acceptance gate, the Windows installer EULA page, and per-tab lazy-loading of the charts route; v3.7.1 was a desktop-build hotfix (installer EULA via `bundle.licenseFile` RTF — see gotcha #15). **v3.8.0** added the **Android APK** target: same React + Tauri app shipped as a sideloadable arm64-v8a `.apk` (`release_android.yml`, post-signed), attached to the same draft Release as the desktop installers. It also fixed the bundle `identifier` to be Android-valid (`com.poli0981.freegamesitchio`, gotcha #16) and realigned `tauri.conf.json`/`Cargo.toml`/`about.ts` versions to `3.8.0` (gotcha #18). Mobile UX: Android back button → router history (`useBackButton`), safe-area insets, and a platform-aware sidebar badge ("Desktop app" / "Mobile app"). Added dep: `@tauri-apps/api`. CI note: the Android JDK setup must NOT use `cache: gradle` — `gen/android` is gitignored and generated mid-job, so there are no gradle files at checkout to key on (it hard-fails); rust-cache + npm cache still apply.
`main` is the trunk. Tags `v3.0.0` through `v3.8.0` are released (all GPG-signed); **v3.9.0 is implemented but pending release** (awaiting test + authorization). The webapp is published at `https://poli0981.github.io/free-games-itchio-list/app/`. v3.7.0 added the first-launch legal-acceptance gate, the Windows installer EULA page, and per-tab lazy-loading of the charts route; v3.7.1 was a desktop-build hotfix (installer EULA via `bundle.licenseFile` RTF — see gotcha #15). **v3.8.0** added the **Android APK** target: same React + Tauri app shipped as a sideloadable arm64-v8a `.apk` (`release_android.yml`, post-signed), attached to the same draft Release as the desktop installers. It also fixed the bundle `identifier` to be Android-valid (`com.poli0981.freegamesitchio`, gotcha #16) and realigned `tauri.conf.json`/`Cargo.toml`/`about.ts` versions to `3.8.0` (gotcha #18). Mobile UX: Android back button → router history (`useBackButton`), safe-area insets, and a platform-aware sidebar badge ("Desktop app" / "Mobile app"). Added dep: `@tauri-apps/api`. CI note: the Android JDK setup must NOT use `cache: gradle` — `gen/android` is gitignored and generated mid-job, so there are no gradle files at checkout to key on (it hard-fails); rust-cache + npm cache still apply. **v3.9.0** raises the Android APK floor from `minSdkVersion` 24 (Android 7.0) to **30 (Android 11)** — the OS-level install gate, chosen for security hardening + patch availability + our tested range, at ≈86.9% device reach (gotcha #19); docs (`TAURI.md`, both READMEs, `docs/pc_spec.md` + VI mirrors) updated with cited data, and the changelog backfilled the previously-missing `[3.8.0]` entry.
+4 -2
View File
@@ -85,8 +85,10 @@ asks nicely first):
build, just signed by me instead of Google.
Notes: **arm64-v8a only** (every phone since ~2017 — 32-bit-only devices aren't supported), and
Android **7.0+** (API 24). Building it yourself is in the Android section of
[`webapp/TAURI.md`](webapp/TAURI.md).
Android **11+** (API 30). Older versions can't install it — that's deliberate: it keeps the floor
at a release that still gets security hardening and that we actually test on (≈87% of active
devices; [why](webapp/TAURI.md#why-android-11-api-30)). Building it yourself is in the Android
section of [`webapp/TAURI.md`](webapp/TAURI.md).
## How it works
+1 -1
View File
@@ -61,7 +61,7 @@ Không lên Play Store — chỉ cần tải `.apk` về và cài tay (Android c
2. Bấm vào file. Android sẽ hỏi **cho phép cài từ nguồn này** (trình duyệt / trình quản lý file) — hãy bật lên (Cài đặt → *Ứng dụng* → *Truy cập đặc biệt* → *Cài ứng dụng không xác định*).
3. Chấp nhận cảnh báo "không từ Play Store" và cài. Vẫn là app y hệt bản web/desktop, chỉ là do mình ký thay vì Google.
Lưu ý: **chỉ arm64-v8a** (mọi điện thoại từ ~2017 — không hỗ trợ máy 32-bit), và Android **7.0+** (API 24). Cách tự build có trong mục Android của [`webapp/TAURI.md`](webapp/TAURI.md).
Lưu ý: **chỉ arm64-v8a** (mọi điện thoại từ ~2017 — không hỗ trợ máy 32-bit), và Android **11+** (API 30). Bản cũ hơn sẽ không cài được — đây là cố ý: giữ sàn ở phiên bản còn được vá bảo mật và là phiên bản mình thật sự test (≈87% thiết bị đang hoạt động; [lý do](webapp/TAURI.md#why-android-11-api-30)). Cách tự build có trong mục Android của [`webapp/TAURI.md`](webapp/TAURI.md).
## Cách hoạt động
+14
View File
@@ -33,6 +33,20 @@ mobile emulation không thay thế được sign-off):
Nếu có bug layout xuất hiện trên các máy này, vui lòng kèm tên thiết bị
+ iOS version + browser khi báo issue.
### Android APK (Tauri)
File `.apk` cài tay (`minSdkVersion` 30 / Android 11) được test trên:
| Thiết bị | Android | Ghi chú |
|---------|---------|--------|
| Máy ảo (AVD) | 11 → mới nhất | system image arm64-v8a |
| vivo 1907 | 12 | sign-off máy thật |
`minSdkVersion` 30 nghĩa là chính hệ điều hành từ chối cài trên Android < 11, nên
sàn đã test cũng là phiên bản thấp nhất được ship. Lý do (bảo mật + phạm vi test,
không phải sàn tính năng JS) nằm trong
[`webapp/TAURI.md`](../../../webapp/TAURI.md#why-android-11-api-30).
## Xem thêm
- [`dev_env.md`](dev_env.md) — IDE, toolchain ngôn ngữ, dev workflow.
+14
View File
@@ -30,6 +30,20 @@ mobile emulation is not a sign-off substitute):
If a layout bug ships, it likely also reproduces on these devices — please
include the device + iOS version + browser when filing a mobile-only issue.
### Android APK (Tauri)
The sideloadable `.apk` (`minSdkVersion` 30 / Android 11) is signed off on:
| Device | Android | Notes |
|--------|---------|-------|
| Emulator (AVD) | 11 → latest | arm64-v8a system images |
| vivo 1907 | 12 | real-phone sign-off |
`minSdkVersion` 30 means the OS itself refuses to install on Android < 11, so the
tested floor is also the lowest version we ship to. Rationale (security + tested
range, not a JS-feature floor) is in
[`webapp/TAURI.md`](../webapp/TAURI.md#why-android-11-api-30).
## See also
- [`dev_env.md`](dev_env.md) — IDE, language toolchains, and dev workflow.
+30 -3
View File
@@ -124,9 +124,36 @@ npm run tauri -- android build --apk --target aarch64 # release (unsigned
```
We ship **arm64-v8a only** (every phone since ~2017; smaller download). `minSdkVersion`
is **24** (Android 7.0 — the floor for SubtleCrypto / OpenPGP.js / IndexedDB, set in
`tauri.conf.json` `bundle.android`). `versionName`/`versionCode` derive from the
`tauri.conf.json` version (`versionCode = major*1e6 + minor*1e3 + patch`).
is **30** (Android 11), set in `tauri.conf.json` `bundle.android`. `versionName`/`versionCode`
derive from the `tauri.conf.json` version (`versionCode = major*1e6 + minor*1e3 + patch`).
#### Why Android 11 (API 30)?
The floor was **24** (Android 7.0) through v3.8.0; v3.9.0 raised it to **30**. The reasoning,
stated honestly so it's defensible:
- **It's not a JS-feature floor.** The Android System WebView is independently updatable from
the Play Store down to API 24, so SubtleCrypto / OpenPGP.js / IndexedDB / ES2020 work fine on
older OSes too. That is *not* the binding constraint.
- **Security + patch availability is the constraint.** Android 11 brought scoped-storage
enforcement, one-time and auto-reset permissions, and a tighter sandbox. Older releases are
also off Google's AOSP monthly Security Bulletins (Android 10 ended 2023-03-06, Android 11
itself ended 2024-02-05; only Android 14/15/16 are still on the bulletins as of mid-2026).
- **Tested range is the other constraint.** We only validate on Android 11+ (see
[`docs/pc_spec.md`](../docs/pc_spec.md)); shipping a floor we haven't tested is the real risk.
- **Reach cost is small.** API 30+ ≈ 86.9% of active devices (was 96.6% at API 24) — we drop
only the pre-2020 long tail.
`minSdkVersion` is *also* the install block: Android's package installer refuses an APK whose
`minSdkVersion` exceeds the device's API level ("app not installed / incompatible"), so there's
no runtime version check by design.
Data sources: [endoflife.date/android](https://endoflife.date/android),
[Android Security Bulletins](https://source.android.com/docs/security/bulletin),
[StatCounter version share](https://gs.statcounter.com/android-version-market-share/mobile/worldwide/),
[apilevels.com](https://apilevels.com/) (StatCounter cumulative distribution).
**Tested on:** emulator Android 11 → latest; real phone vivo 1907 / Android 12.
### Signing for distribution
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "free-games-itchio-webapp"
version = "3.8.0"
version = "3.9.0"
description = "Itch.io free games catalog browser & editor"
authors = ["poli0981"]
license = "MIT"
+2 -2
View File
@@ -1,7 +1,7 @@
{
"$schema": "https://schema.tauri.app/config/2",
"productName": "Itch.io Free Games DB",
"version": "3.8.0",
"version": "3.9.0",
"identifier": "com.poli0981.freegamesitchio",
"build": {
"beforeDevCommand": "npm run dev",
@@ -30,7 +30,7 @@
"active": true,
"targets": "all",
"android": {
"minSdkVersion": 24
"minSdkVersion": 30
},
"icon": [
"icons/32x32.png",
+1 -1
View File
@@ -8,7 +8,7 @@ export interface ThirdParty {
export const APP = {
name: 'Itch.io Free Games DB',
version: '3.8.0',
version: '3.9.0',
repo: 'https://github.com/poli0981/free-games-itchio-list',
license: 'MIT',
buildDate: typeof __BUILD_DATE__ !== 'undefined' ? __BUILD_DATE__ : 'dev',