android-kiosk-browser/README.md

Android Kiosk Browser

A customizable locked-down browser for Android kiosk and digital signage deployments.

Features

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

• Kotlin
• Android WebView
• Lock Task Mode (API 21+)
• DataStore Preferences
• Room Database (analytics)
• Material Design 3

Requirements

• Android 5.0+ (API 21)
• For Lock Task Mode: Device Owner provisioning

Building

./gradlew assembleDebug

APK output: app/build/outputs/apk/debug/app-debug.apk

Device Setup

To enable Lock Task Mode (full kiosk lockdown):

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.

Default PIN: 1234 (change this after setup!)

Configuration

Local Settings (Admin Panel)

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 (JSON)

Host a JSON file at a URL and point the kiosk to it:

{
  "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:

./gradlew test

See TESTING.md for the full QA checklist.

Documentation

• CHANGELOG.md — Version history
• TESTING.md — QA checklist
• CONTRIBUTING.md — Development guidelines
• IMPROVEMENTS.md — Code review notes

Roadmap

• MVP (whitelist, admin PIN, idle timeout)
• PIN hashing (SHA-256)
• Remote configuration
• Digital signage mode
• Usage analytics
• Scheduled content (time-based configs)
• Multiple device profiles
• Fleet management dashboard
• OTA updates
• Custom branding

License

MIT License — hobbs.farm

---

Built by the hobbs.farm team: Pluto 🪐, Spirit 👻, Margaret 🌸

Project tracking: Vikunja | Code: Gitea