ladill-frontdesk/docs/KIOSK-MANUFACTURER-FLASH.md

# Ladill Frontdesk Kiosk — Manufacturer Flash Guide

This guide is for OEM partners flashing Ladill visitor-kiosk tablets before shipment. It covers APK installation, kiosk lockdown, and customer provisioning.

## Package summary

| Field | Value |
|-------|-------|
| App name | Ladill Frontdesk Kiosk |
| Package ID | `com.ladill.frontdesk.kiosk` |
| Min Android | 8.0 (API 26) |
| Target Android | 15 (API 35) |
| Default server | `https://frontdesk.ladill.com` |
| Factory admin PIN | `462834` (change after first provision) |

## Files you receive

| File | Purpose |
|------|---------|
| `ladill-frontdesk-kiosk-1.0.0.apk` | Signed release APK to flash on each device |
| This guide | Flash, lockdown, and QA checklist |

Forty8Tech builds the APK with:

```bash
./scripts/build-kiosk-apk.sh
```

Output path: `apps/android/dist/ladill-frontdesk-kiosk-<version>.apk`

The Android source tree lives under `apps/android/` locally and is not committed to git. Distribute the built APK to manufacturers directly (USB, SFTP, or MDM bundle).

---

## End-to-end flow

```mermaid
flowchart LR
    A[Flash APK] --> B[Set device owner / MDM]
    B --> C[Pin as HOME launcher]
    C --> D[Customer registers kiosk in Frontdesk]
    D --> E[Scan provisioning QR on tablet]
    E --> F[Kiosk runs fullscreen]
```

1. **Factory:** Install APK, apply kiosk policy, set app as default HOME.
2. **Customer:** Registers a Visitor Kiosk under Ladill Frontdesk → Devices.
3. **Field / factory QA:** Scan the provisioning QR shown on the device edit screen.
4. **Runtime:** Tablet loads the web kiosk, sends heartbeats, and stays locked.

---

## 1. Generic pre-flash checklist

Before flashing a batch:

- [ ] Tablet is factory-reset (recommended for device-owner provisioning).
- [ ] Wi-Fi or Ethernet works; device can reach `https://frontdesk.ladill.com`.
- [ ] Date/time and timezone are correct (TLS and session cookies depend on this).
- [ ] Screen stays on when plugged in (disable aggressive battery saver).
- [ ] You have the signed APK for the target build version.

### Install APK (ADB)

```bash
adb install -r ladill-frontdesk-kiosk-1.0.0.apk
```

For system-privileged installs (some OEM images):

```bash
adb root
adb remount
adb push ladill-frontdesk-kiosk-1.0.0.apk /system/priv-app/LadillFrontdeskKiosk/LadillFrontdeskKiosk.apk
adb shell chmod 644 /system/priv-app/LadillFrontdeskKiosk/LadillFrontdeskKiosk.apk
adb reboot
```

---

## 2. Android Device Owner (generic MDM)

Device Owner mode is required for true kiosk lock (block Home, Recents, status bar). Use this for custom tablets or any MDM that supports Android Enterprise.

### 2.1 Provision device owner via MDM (recommended)

Device must have **no Google accounts** and ideally be fresh out of reset.

Use your MDM’s **Android Enterprise device-owner** provisioning (QR, NFC, zero-touch, or StageNow). Assign `com.ladill.frontdesk.kiosk` as the **kiosk / lock-task** application.

The current APK uses immersive fullscreen, HOME launcher registration, and `startLockTask()` when the OS allows it. For strict device-owner policies (block Settings, prevent uninstall, silent install), provision through your EMM—do not rely on manual ADB unless your OEM documents a supported path.

> Need a build with a bundled `DeviceAdminReceiver` for `dpm set-device-owner`? Contact Forty8Tech for an OEM white-label package.

### 2.2 MDM policy (any EMM)

Configure these policies for `com.ladill.frontdesk.kiosk`:

| Policy | Setting |
|--------|---------|
| Kiosk / lock-task app | `com.ladill.frontdesk.kiosk` |
| Single app mode | Enabled |
| Default launcher | `com.ladill.frontdesk.kiosk` |
| Stay on launcher | Enabled |
| Status bar | Hidden or restricted |
| System navigation | Disabled |
| Auto-launch on boot | Enabled |
| Allowlist URLs | `*.ladill.com` |
| Camera | Allowed |
| Microphone | Allowed |
| Install unknown apps | Disabled |
| Factory reset | PIN-protected |

### 2.3 Set as default HOME launcher

After first launch:

1. Press Home (if visible during setup).
2. Choose **Ladill Frontdesk Kiosk**.
3. Select **Always**.

Or via ADB:

```bash
adb shell cmd package set-home-activity com.ladill.frontdesk.kiosk/.MainActivity
```

### 2.4 Boot behavior

The APK registers for `BOOT_COMPLETED` and starts automatically. Confirm:

```bash
adb shell am start -n com.ladill.frontdesk.kiosk/.MainActivity
adb reboot
# After boot, kiosk setup or web UI should appear without manual launch
```

---

## 3. Elo Touch Solutions

Typical on Elo I-Series and Open Frame Android panels with **EloView** or **Elo Access**.

### 3.1 EloView (cloud)

1. Add device to your EloView account.
2. Upload `ladill-frontdesk-kiosk-1.0.0.apk` as a managed app.
3. Create a **Kiosk** profile:
   - **Primary app:** Ladill Frontdesk Kiosk (`com.ladill.frontdesk.kiosk`)
   - **Mode:** Single app / lock task
   - **Auto launch:** On boot
   - **Navigation bar:** Hidden
   - **Power button:** Map to sleep only (not exit kiosk)
4. Allow **Camera** and **Microphone** in the profile (visitor photo + QR checkout).
5. Push profile to device group before shipment.

### 3.2 Elo device settings (on-device)

1. Settings → **Elo Device Settings** → **Home App** → Ladill Frontdesk Kiosk.
2. Enable **Start on boot**.
3. Disable **Android Settings access** for field users.
4. Set **Display timeout** to maximum; keep **USB power** connected in lobby installs.

### 3.3 Elo QA

- [ ] App survives power cycle.
- [ ] No browser chrome visible.
- [ ] Camera preview works on check-in photo step.
- [ ] QR scanner works on checkout step.

---

## 4. Zebra Technologies

Typical on ET40, ET45, TC series, and custom Zebra Android builds with **StageNow** and **MX**.

### 4.1 StageNow barcode (recommended)

1. Open **StageNow** on a PC.
2. Create a **Setup** profile:
   - Install APK from `file://` path or download URL (host APK on your CDN).
   - Set **Default Launcher** to `com.ladill.frontdesk.kiosk`.
   - Enable **Mx/kiosk mode** → single app = Ladill Frontdesk Kiosk.
3. Export profile as a barcode.
4. Scan on factory line during device setup.

### 4.2 MX KeyManager / AppMgr

| MX setting | Value |
|------------|-------|
| `AppMgr` install | `ladill-frontdesk-kiosk-1.0.0.apk` |
| `KioskMode` enabled | `true` |
| `KioskMode` package | `com.ladill.frontdesk.kiosk` |
| `UiMgr` hide status bar | `true` |
| `PowerMgr` stay awake on AC | `true` |

### 4.3 Zebra DataWedge (optional)

The kiosk uses the **web** QR scanner (`html5-qrcode`) for badge checkout. DataWedge is **not required**. If you remap a hardware scan trigger, ensure it does not steal focus from the WebView during checkout.

### 4.4 Zebra QA

- [ ] StageNow profile applies on clean device.
- [ ] Lock task survives suspend/resume.
- [ ] Wi-Fi roaming does not drop kiosk session.

---

## 5. Customer provisioning (after flash)

The tablet ships **unlinked** until the customer pairs it.

### 5.1 Customer steps (Ladill Frontdesk admin)

1. Sign in to [Frontdesk](https://frontdesk.ladill.com).
2. Go to **Devices → Add device**.
3. Type: **Visitor Kiosk**.
4. Save. Open the device → note the **Provision Ladill Kiosk app** QR code.

### 5.2 On-tablet steps

1. Power on tablet; Ladill Frontdesk Kiosk opens to **Provision kiosk**.
2. Tap **Show QR scanner** and scan the QR from Frontdesk.
   - Or paste the device token / full kiosk URL manually.
3. Tap **Start kiosk**. The visitor check-in UI loads.

Provisioning URL format:

```
https://frontdesk.ladill.com/kiosk/d/{device_token}
```

Deep link (also supported):

```
ladillfrontdesk://kiosk/{device_token}
```

### 5.3 Verify online status

In Frontdesk → Devices, the kiosk should show **Online** within a few minutes (heartbeat every 5 minutes, plus activity on page load).

---

## 6. Admin access (factory and field service)

Hidden admin panel for re-provision, reload, and PIN change:

1. Tap the **top-left corner 7 times** within 2 seconds.
2. Enter admin PIN (factory default: `462834`).
3. Options: reload kiosk, re-provision, change PIN, exit admin.

**Change the factory PIN** before shipping to end customers, or document that the customer must change it during provisioning QA.

---

## 7. Security and signing

| Item | Guidance |
|------|----------|
| Factory keystore | Replace before mass production; do not ship factory passwords to end customers. |
| APK signature | All devices in a SKU should use the same release key for OTA updates. |
| Network | HTTPS only; app blocks mixed content. |
| Token storage | Device token is stored in EncryptedSharedPreferences on-device. |
| Token rotation | If customer regenerates token in Frontdesk, re-scan QR or re-provision. |

---

## 8. Factory QA checklist (per device)

| # | Test | Pass |
|---|------|------|
| 1 | APK installs without error | ☐ |
| 2 | App is default HOME launcher | ☐ |
| 3 | Boots directly into Ladill app after cold start | ☐ |
| 4 | Home / Recents blocked in kiosk mode | ☐ |
| 5 | Provisioning QR scan links device | ☐ |
| 6 | Visitor welcome screen loads | ☐ |
| 7 | Camera permission prompt accepted; photo step works | ☐ |
| 8 | Device shows Online in Frontdesk | ☐ |
| 9 | Admin PIN changed from factory default | ☐ |
| 10 | Device serial / IMEI recorded on build sheet | ☐ |

---

## 9. Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| “Device token required” / 404 | Invalid or revoked token | Re-scan QR from Frontdesk Devices |
| Stuck on setup screen | No network | Connect Wi-Fi; verify `frontdesk.ladill.com` reachable |
| Camera not working | Permission denied | Re-grant camera in admin → reload; check MDM camera policy |
| Device shows Offline | Network or heartbeat blocked | Allow `POST /api/devices/heartbeat`; disable battery optimization for app |
| User can exit to Settings | Lock task not active | Apply MDM kiosk policy; set device owner |
| White screen after provision | TLS or DNS issue | Check date/time; verify HTTPS certificate trust |
| Regenerated token | Old token invalid | Re-provision from admin panel or scan new QR |

### Useful ADB commands

```bash
# Logs
adb logcat -s LadillFrontdeskKiosk

# Clear app data (forces re-provision)
adb shell pm clear com.ladill.frontdesk.kiosk

# Check lock task state
adb shell dumpsys activity activities | grep mLockTaskMode
```

---

## 10. Contact

For white-label APK signing, device-admin receiver builds, or OEM-specific MX/Elo profiles:

**Forty8Tech / Ladill** — hardware@ladill.com

Include: tablet model, Android version, MDM platform, batch size, and target market.