# 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

```bash
./gradlew assembleDebug
```

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

## Device Setup

To enable Lock Task Mode (full kiosk lockdown):

```bash
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:

```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

---

*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)*