455f8498f7
All checks were successful
APK-BUILD/pipeline/head This commit looks good
- Kiosk mode: scanning AppConfig.KIOSK_BARCODE toggles Android Lock Task mode (persisted). As device owner (KioskAdminReceiver) it is a full lockdown and the app becomes the persistent home screen; otherwise it falls back to screen pinning. "Salir" and Back-to-exit are disabled while kiosk mode is on. - Status strip: app-drawn bar showing only Wi-Fi status and battery percentage; system bars stay hidden. - Renderer crash: onRenderProcessGone replaces the WebView and reloads the last URL; repeated crashes show an error screen instead. - Error screen: per-cause messages (no Wi-Fi with auto-retry on reconnect, server unreachable, 5xx, SSL) and an "Ir al inicio" button; 4xx pages are left to the site. - Mixed content is never allowed. - Admin volume-key hold reduced to 3 seconds. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
104 lines
5.5 KiB
Markdown
104 lines
5.5 KiB
Markdown
# Joykoo Scanner
|
|
|
|
Aplicación nativa de Android que funciona como navegador dedicado de pantalla completa para el sistema web de Joykoo (`smart.joykoo.mx`), diseñada para escáneres industriales de códigos de barras y QR.
|
|
|
|
## Características
|
|
|
|
- **WebView en pantalla completa** — Carga el sitio web de la empresa sin barra de direcciones ni controles del navegador
|
|
- **Supresión del teclado virtual** — El teclado en pantalla de Android nunca aparece, mientras que la entrada del escáner de códigos de barras (modo HID/teclado) funciona normalmente
|
|
- **Modo kiosco** — Pantalla siempre encendida, modo inmersivo, navegación restringida al dominio de la empresa
|
|
- **Persistencia de sesión** — Cookies y almacenamiento local persisten entre reinicios de la aplicación
|
|
- **Manejo de errores** — Mensajes distintos para sin Wi-Fi (recarga automática al reconectar), servidor sin respuesta, error del servidor (5xx) y certificado inválido; recuperación automática si el motor de la página se cierra
|
|
- **Barra de estado propia** — Solo muestra Wi-Fi (intensidad / sin internet) y porcentaje de batería
|
|
- **Modo kiosco (bloqueo)** — Se activa/desactiva escaneando el código de kiosco (ver abajo)
|
|
- **Salida protegida** — Se requieren 3 pulsaciones rápidas del botón Atrás para salir; menú de administrador (salir / mostrar u ocultar teclado) al mantener presionados Subir y Bajar volumen 3 segundos, o al escanear el código de administrador
|
|
|
|
## Requisitos
|
|
|
|
- Android 7.0+ (API 24)
|
|
- Dispositivo con escáner de códigos de barras integrado en modo HID/teclado
|
|
- Conexión Wi-Fi al servidor de la empresa
|
|
|
|
## Compilación
|
|
|
|
### Prerrequisitos
|
|
|
|
- JDK 17
|
|
- Android SDK con:
|
|
- `platform-tools`
|
|
- `platforms;android-34`
|
|
- `build-tools;34.0.0`
|
|
|
|
### Usando Android Studio
|
|
|
|
Abrir el proyecto y compilar normalmente.
|
|
|
|
### Línea de comandos
|
|
|
|
```bash
|
|
export JAVA_HOME=/ruta/a/jdk-17
|
|
export ANDROID_HOME=/ruta/a/android-sdk
|
|
|
|
./gradlew assembleDebug # APK de depuración
|
|
./gradlew assembleRelease # APK de producción (requiere configurar firma)
|
|
```
|
|
|
|
El APK resultante se encuentra en `app/build/outputs/apk/`.
|
|
|
|
## Configuración
|
|
|
|
Todos los valores configurables están en un solo archivo:
|
|
|
|
**`app/src/main/java/mx/joykoo/scanner/AppConfig.kt`**
|
|
|
|
| Parámetro | Descripción | Valor por defecto |
|
|
|---|---|---|
|
|
| `HOME_URL` | URL que se carga al iniciar | `https://smart.joykoo.mx/` |
|
|
| `ALLOWED_HOSTS` | Dominios permitidos dentro del WebView | `smart.joykoo.mx`, `joykoo.mx` |
|
|
| `BACK_PRESS_EXIT_COUNT` | Pulsaciones rápidas de Atrás para salir | 3 |
|
|
| `ADMIN_VOLUME_HOLD_MS` | Tiempo (ms) con ambos botones de volumen presionados para abrir el menú de administrador | 3000 |
|
|
| `KIOSK_BARCODE` | Código que, al escanearse (modo Intent), activa/desactiva el modo kiosco | `JOYKOO-KIOSK-…` |
|
|
| `ADMIN_BARCODE` | Código que, al escanearse (modo Intent), abre el menú de administrador | `JOYKOO-ADMIN-…` |
|
|
|
|
## Uso del escáner
|
|
|
|
1. El usuario toca un campo de texto en la página web
|
|
2. El campo recibe el foco — **el teclado virtual no aparece**
|
|
3. El usuario escanea un código de barras o QR
|
|
4. El texto escaneado aparece en el campo
|
|
5. Si el escáner envía Enter al final, la página lo procesa normalmente
|
|
|
|
## Modo kiosco
|
|
|
|
Escanear `KIOSK_BARCODE` activa o desactiva el bloqueo (Lock Task de Android). El estado se guarda y se vuelve a aplicar al abrir la app. Mientras está activo, el menú de administrador no ofrece "Salir" y el botón Atrás no cierra la app.
|
|
|
|
Para un bloqueo completo (sin botones Inicio/Recientes, sin panel de notificaciones, sin aviso del sistema y regreso automático a la app tras reiniciar), la app debe ser **propietaria del dispositivo** (*device owner*). En un dispositivo recién restablecido y **sin cuentas** (Google, etc.):
|
|
|
|
```bash
|
|
adb install app-release.apk
|
|
adb shell dpm set-device-owner mx.joykoo.scanner/.KioskAdminReceiver
|
|
```
|
|
|
|
Importante:
|
|
- Instale el APK **firmado de producción** antes de este paso. Una app propietaria no se puede desinstalar (solo con restablecimiento de fábrica), así que no se podrá cambiar a un APK firmado con otra clave.
|
|
- Sin *device owner*, el modo kiosco usa la "fijación de pantalla" de Android: el sistema pide confirmación y el usuario puede salir manteniendo Atrás + Recientes.
|
|
- Desactive el atajo de accesibilidad de volumen (Ajustes → Accesibilidad) para que mantener ambos botones de volumen no active TalkBack.
|
|
|
|
## Estructura del proyecto
|
|
|
|
```
|
|
app/src/main/java/mx/joykoo/scanner/
|
|
├── AppConfig.kt — Configuración centralizada
|
|
├── MainActivity.kt — Actividad principal (kiosco, WebView, navegación)
|
|
├── NoSoftKeyboardWebView.kt — WebView que suprime el teclado virtual
|
|
├── ScannerIntegration.kt — Interfaz para integración con el escáner
|
|
├── BroadcastScannerIntegration.kt — Recepción de códigos en modo Intent
|
|
├── KioskController.kt — Modo kiosco (Lock Task, pantalla de inicio)
|
|
├── KioskAdminReceiver.kt — Componente de propietario del dispositivo
|
|
└── StatusStrip.kt — Barra de estado propia (Wi-Fi y batería)
|
|
```
|
|
|
|
## Modo de salida por Intent (broadcast)
|
|
|
|
Además del modo teclado (keystroke), la aplicación acepta escáneres configurados en **modo Intent**. El código recibido se escribe en el campo con foco (o, si no hay ninguno, en el primer campo de búsqueda/texto visible) y se envía Enter al final. Las acciones y claves extra soportadas (Urovo, Newland y otros) están en `SCANNER_BROADCAST_ACTIONS` / `SCANNER_BROADCAST_EXTRAS` en `AppConfig.kt`; si el dispositivo usa otra acción, agréguela ahí.
|