android-webview-kiosk/CLAUDE.md

android-webview-kiosk

Android TV app: fullscreen WebView showing one hardcoded Grafana dashboard. Runs on the living-room Sony Bravia KD-65XE9305 (Android 8.0, API 26; Android System WebView updates independently via Play Store — currently v138). Launched remotely through the Bravia REST IP-control API by Control4 (driver lives in a separate project). See README.md for the API sequence.

Lab project — with deviations

This is a lab project (lab skill conventions apply) EXCEPT:

• No container image, no helm chart, no /livez//readyz — artifact is an APK.
• No nix build: gradle needs network for Maven deps. The flake is a dev shell only. All builds run as nix develop --command gradle ....
• Agents cannot run nix/gradle/adb here — ask the user to run commands and report output.

NixOS aapt2 workaround

AGP cannot run the Maven-downloaded aapt2 on NixOS (dynamically linked generic Linux binary). The nix shellHook rewrites the android.aapt2FromMavenOverride line in gradle.properties to point at the SDK's nix-patched aapt2 on every nix develop. The sentinel value __NIX_SHELLHOOK_SETS_THIS__ is what's tracked in git; the shellHook replaces it before any gradle command runs.

Commands (user-run, from repo root)

• Tests: nix develop --command gradle --no-daemon :app:testReleaseUnitTest
• Release APK: nix develop --command gradle --no-daemon :app:assembleRelease → app/build/outputs/apk/release/app-release.apk
• Sideload: adb connect <tv-ip>:5555 && adb install -r <apk> (bump versionCode in app/build.gradle.kts first for upgrades)

Key facts

• Package/applicationId: cz.c3c.webviewkiosk; repo name keeps the android- prefix, the package can't (hyphens illegal).
• Dashboard URL hardcoded in MainActivity.DASHBOARD_URL — changing it means rebuild + sideload. Intentional: keeps Control4 integration to a single parameterless launch call.
• signing/release.keystore is committed on purpose (private repo, LAN-only kiosk) so every build is upgrade-compatible. Don't reuse the key.
• minSdk 26 is a hard floor — the TV never gets newer Android.
• LEANBACK_LAUNCHER category + android:banner are what make the app visible to the Bravia API's getApplicationList/setActiveApp. Don't remove either.
• App URI (from getApplicationList): com.sony.dtv.cz.c3c.webviewkiosk.cz.c3c.webviewkiosk.MainActivity
• setActiveApp alone wakes the TV from standby — no separate setPowerStatus call needed. Control4 driver can skip the wake step.