# Mobile app

UHPPOTE Desk includes a mobile app for operators: a page made for phones, at **`/m`**, that can be installed on the home screen like an app (a PWA, without app stores). It shows the doors with their live state, opens them with a confirmation, lists the latest events, and receives **push notifications** even when it is closed.

## Requirements

- **HTTPS.** Browsers allow installation, push notifications and fingerprint/Face ID only on HTTPS sites. Publish UHPPOTE Desk through a reverse proxy with a certificate (e.g. Nginx Proxy Manager with Let's Encrypt) and set:

  ```env
  PUBLIC_URL=https://doors.example.com
  SECURE_COOKIES=true
  ```

  `PUBLIC_URL` is the address the phones use. Fingerprint/Face ID are bound to that host name; if it changes, the phones must activate them again.
- The reverse proxy must forward the WebSocket (`/api/ws`, live state) and the `Host`/`X-Forwarded-*` headers. With Nginx Proxy Manager enable *Websockets Support*.
- **iPhone**: push notifications need iOS 16.4 or later and the app installed on the home screen (Safari → Share → *Add to Home Screen*). **Android**: Chrome, Edge or Samsung Internet; Chrome offers *Install app* by itself.

## Installing the app

1. Open `https://<your address>/m` on the phone.
2. Log in with **Remember this device** checked (it is checked by default on phones).
3. Add it to the home screen. From then on the icon opens the app full screen.

The header of the full application has a phone icon that opens `/m`; administrators find the address also in *Administration → Mobile app*.

## Remembered devices

"Remember this device" gives the phone its own long login instead of the 12-hour session:

- with **fingerprint/Face ID registered** on the device, the login has **no expiry**;
- otherwise it lasts **30–180 days** (in steps of 30) from the login, as set by the administrator.

The administrator sees every remembered device in *Administration → Mobile app* (operator, device, last use and IP, fingerprint/Face ID, push, expiry) and can **revoke** it: the phone is logged out immediately and its push notifications and fingerprint/Face ID are deleted. Logging out from the app does the same. Changing the password logs out the operator's other devices; an administrator resetting a password logs out all of them. A disabled operator can no longer use any device.

## Opening doors

The app lists the doors: the ones the operator may open (role, zones) have the open button, the others are view-only. The confirmation is set by the administrator (*Administration → Mobile app → Door opening confirmation*):

| Confirmation | How |
|---|---|
| **Hold the button** | The button must be held down for about a second: a touch in the pocket does not open. |
| **Fingerprint / Face ID** | Every opening from a remembered device is confirmed with the phone's fingerprint, Face ID (or the phone's PIN, if that is how the phone verifies its user). |

With fingerprint/Face ID, each phone activates it once (the app asks for it). The confirmation is checked by the server: it is bound to the phone, to the door and to that single opening, so it cannot be reused or moved to another door.

The confirmation applies to remembered devices. Operators logged in with a password at a desk (normal session) open doors as before; API tokens are not affected either.

## Push notifications

In the app, *Settings → Push notifications*:

- **Notifications on this phone** turns them on (the browser asks for permission);
- **Events**: the same events as notifications and webhooks (access denied, alarms, controller offline, unusual times…);
- **Only these doors**: optional filter;
- **Automation rules**: also the firings of the [rules](RULES.md);
- **Send a test** checks the delivery.

**Android, installed app**: installing the app moves its notifications from Chrome to the installed app, which has its own notification permission in Android. Some phones (e.g. Realme/OPPO with ColorOS) deny it by default: then Chrome drops the subscription and notifications stop. Allow them in *Android Settings → Apps → UHPPOTE Desk → Notifications*; when the app is opened again it restores the notifications with the same preferences, or explains what to do. Banner and sound of the notifications are set there too (by default some phones show web notifications without a banner).

Notifications about a door the operator may open have an **Open** action (Android). With *Hold the button* the action opens the door directly; with *Fingerprint / Face ID* it opens the app on that door, where the opening is confirmed. On iPhone notifications have no action buttons: a tap opens the app on the door.

Push notifications use the browser's push service (Google for Chrome/Android, Apple for Safari/iPhone, Mozilla for Firefox): the content is encrypted end to end with keys generated by this installation (VAPID), so the push service only sees that a message passes. For notifications that never leave your network use [ntfy](NOTIFICATIONS.md#ntfy).

## Troubleshooting

| Symptom | Solution |
|---|---|
| No *Install* / *Add to Home Screen*, push and fingerprint not available | The site is not on HTTPS: publish it through the reverse proxy |
| "Fingerprint / Face ID confirmation not valid" on every attempt | `PUBLIC_URL` differs from the address in the phone's browser: set it to exactly that address (scheme and host) |
| Live state does not update in the app | WebSocket not forwarded by the reverse proxy |
| iPhone: no notifications | Install the app on the home screen first (iOS 16.4+), then enable notifications from the app |
| Android: notifications stopped after installing the app | Allow notifications for the app in *Settings → Apps → UHPPOTE Desk → Notifications*, then open the app |
| Android: notifications only in the notification shade, no banner | In the notification settings of the app (or of Chrome, if not installed) enable banners / pop-up notifications |
| The phone asks to log in again | The device expired (no fingerprint/Face ID), was revoked, or the password was changed |