JoykooSmartApp/README.md

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

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.):

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í.