diff --git a/README.md b/README.md index 9f9ca03..b54ba5e 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,28 @@ A customizable locked-down browser for Android kiosk and digital signage deployments. -## Features (MVP) +## Features -- **Fullscreen WebView** - Immersive mode, no address bar or browser chrome -- **URL Whitelist** - Only allow configured domains -- **Lock Task Mode** - Disables home/back/recent buttons -- **Admin PIN Exit** - PIN-protected escape from kiosk mode -- **Auto-launch on Boot** - Starts automatically when device powers on -- **Idle Timeout** - Returns to homepage after inactivity -- **Admin Settings** - Configure whitelist, homepage, timeout, PIN +### Core (v1.0) +- **Fullscreen WebView** — Immersive mode, no address bar or browser chrome +- **URL Whitelist** — Only allow configured domains with proper boundary matching +- **Lock Task Mode** — Disables home/back/recent buttons +- **Admin PIN Exit** — PIN-protected escape from kiosk mode (triple-tap top-left) +- **Auto-launch on Boot** — Starts automatically when device powers on +- **Idle Timeout** — Returns to homepage after inactivity + +### Security (v1.1) +- **PIN Hashing** 🔐 — PINs stored as salted SHA-256 hashes, not plain text +- **Whitelist Bypass Protection** — Proper domain boundary checking + +### Remote Management (v1.1) +- **Remote Configuration** 📡 — Fetch settings from a JSON endpoint (polls every 5 min) +- **Digital Signage Mode** 🖼️ — Auto-rotate through multiple URLs at configurable intervals +- **Usage Analytics** 📊 — Track page views, sessions, and admin access (local SQLite) + +### UX +- **Error Handling** — Graceful network error pages with retry button +- **Loading Indicator** — Progress bar during page loads ## Tech Stack @@ -18,6 +31,7 @@ A customizable locked-down browser for Android kiosk and digital signage deploym - Android WebView - Lock Task Mode (API 21+) - DataStore Preferences +- Room Database (analytics) - Material Design 3 ## Requirements @@ -31,6 +45,8 @@ A customizable locked-down browser for Android kiosk and digital signage deploym ./gradlew assembleDebug ``` +APK output: `app/build/outputs/apk/debug/app-debug.apk` + ## Device Setup To enable Lock Task Mode (full kiosk lockdown): @@ -41,30 +57,74 @@ adb shell dpm set-device-owner farm.hobbs.kioskbrowser/.KioskDeviceAdminReceiver ## Admin Access -Triple-tap the top-left corner of the screen to access admin settings. +**Triple-tap the top-left corner** of the screen to access admin settings. -Default PIN: `1234` +Default PIN: `1234` (change this after setup!) ## Configuration -Settings available in Admin panel: -- Homepage URL -- Allowed domains (comma-separated) -- Idle timeout (seconds) -- Admin PIN +### Local Settings (Admin Panel) -## Future Enhancements +| Section | Settings | +|---------|----------| +| **Basic** | Homepage URL, allowed domains, idle timeout | +| **Remote Config** | Config URL, poll interval | +| **Digital Signage** | Enable, URL list, rotation interval | +| **Security** | Change admin PIN | +| **Analytics** | View/export/clear usage data | -- [ ] Remote configuration -- [ ] Multiple profiles -- [ ] Usage analytics -- [ ] Digital signage mode (URL rotation) -- [ ] Session data clearing on idle +### Remote Configuration (JSON) + +Host a JSON file at a URL and point the kiosk to it: + +```json +{ + "homepage": "https://example.com", + "whitelist": "example.com,*.example.com", + "idle_timeout": "300", + "signage_urls": [ + "https://example.com/slide1", + "https://example.com/slide2" + ], + "signage_interval": "30" +} +``` + +## Testing + +Run unit tests: +```bash +./gradlew test +``` + +See [TESTING.md](TESTING.md) for the full QA checklist. + +## Documentation + +- [CHANGELOG.md](CHANGELOG.md) — Version history +- [TESTING.md](TESTING.md) — QA checklist +- [CONTRIBUTING.md](CONTRIBUTING.md) — Development guidelines +- [IMPROVEMENTS.md](IMPROVEMENTS.md) — Code review notes + +## Roadmap + +- [x] MVP (whitelist, admin PIN, idle timeout) +- [x] PIN hashing (SHA-256) +- [x] Remote configuration +- [x] Digital signage mode +- [x] Usage analytics +- [ ] Scheduled content (time-based configs) +- [ ] Multiple device profiles +- [ ] Fleet management dashboard +- [ ] OTA updates +- [ ] Custom branding ## License -MIT License - hobbs.farm +MIT License — hobbs.farm --- -*Project managed in Vikunja | Docs on Wiki* +*Built by the hobbs.farm team: Pluto 🪐, Spirit 👻, Margaret 🌸* + +*Project tracking: [Vikunja](https://vikunja.hobbs.farm) | Code: [Gitea](https://git.hobbs.farm/pluto/android-kiosk-browser)*