Manual de integración de terminales Android

Estado de integración de UIC Home 3.9.14-dev (código de versión 27), 26 de septiembre de 2026. Esta guía cubre las compilaciones NEWPOS NEW9810 y NEXGO N82. La firma de producción, la distribución de inscripción y cada firmware deben calificarse por separado.

1. Función de UIC Home

UIC Home es el launcher Android administrado y el agente TMS. Mantiene la conexión MQTT autenticada, reporta telemetría e inventario, recibe operaciones durables, descarga aplicaciones y parámetros por HTTPS y aloja la asistencia remota Android. La aplicación de pagos permanece separada.

Use el APK que coincida con el cliente y la marca de hardware. Los APK NEWPOS y NEXGO pueden pertenecer a una misma aplicación/versión lógica en el portal, pero son artefactos específicos por modelo. El identificador de paquete también cambia según cliente, marca y variante debug/release.

2. Requisitos y restricciones

• Un SuperAdmin registró la serie exacta del fabricante bajo el cliente y modelo Android correctos.
• La terminal tiene red confiable, fecha/hora correctas y confianza en el certificado HTTPS/MQTT del TMS.
• El APK proviene de una compilación aprobada y su firmante coincide con la versión instalada cuando se actualiza.
• Instalar el APK no inscribe la terminal. El registro de inscripción de prueba/debug se transfiere mediante una estación autorizada.
• No desinstale UIC Home ni borre sus datos durante una actualización. Esto elimina el secreto del dispositivo, la clave IoT de AndroidKeyStore, el diario de comandos y la configuración.
• No use la limpieza de pruebas conectadas de Gradle en una terminal inscrita; puede desinstalar el paquete.
• Los APK debug y las claves de desarrollo no son credenciales de producción.

3. Instalar con ADB desde una estación de aprovisionamiento

1. Habilite el modo autorizado de depuración/servicio USB y autorice la computadora.
2. Conecte solo la terminal objetivo e identifíquela:

text adb devices -l

1. Instale o actualice conservando los datos:

text adb -s <serie-adb> install -r <ruta-absoluta-al-APK-UIC-Home>

1. Si Android informa conflicto de firma o versión inferior, deténgase. Confirme cliente, marca y certificado. No desinstale para evitar el error en una terminal ya inscrita.
2. Abra UIC Home una vez. La inicialización del SDK de marca la registra como Inicio; si el firmware no acepta, use Establecer UIC Home como aplicación de inicio y el selector Android.

-r conserva datos solo cuando el paquete y la firma son compatibles. No protege datos si antes se elimina la aplicación.

4. Copiar el APK a la memoria del dispositivo

Este método sirve cuando no se permite instalar con ADB pero un técnico autorizado puede usar la interfaz del equipo.

1. Copie el APK aprobado al almacenamiento interno, normalmente Download/Descargas. Con una computadora autorizada puede usar transferencia USB o:

text adb -s <serie-adb> push <ruta-absoluta-al-APK-UIC-Home> /sdcard/Download/UIC-Home.apk

1. Abra el administrador de archivos del fabricante o Archivos > Descargas y seleccione el APK.
2. Si Android solicita Instalar aplicaciones desconocidas, autorice solamente al administrador de archivos durante esta instalación. Firmware administrado puede pedir clave de servicio o aprobación del fabricante.
3. Seleccione Instalar/Actualizar y verifique paquete, versión y firmante contra la liberación aprobada.
4. Abra UIC Home, confirme que es la aplicación Inicio, elimine el APK copiado y desactive el permiso temporal.

Copiar el archivo no evita las políticas de firma Android/fabricante. Algunos firmwares administrados bloquean la transferencia USB o instalación local; use entonces el proceso aprobado por el fabricante.

5. Instalar desde memoria USB u OTG

1. Coloque solo el APK aprobado y su nota/hash de liberación en un medio limpio.
2. Conéctelo mediante el adaptador USB/OTG compatible.
3. Abra el administrador de archivos, explore la unidad USB y seleccione el APK.
4. Siga las mismas verificaciones de origen desconocido, firma y primer inicio.
5. Expulse el medio, elimine copias locales y restaure la política USB/seguridad normal.

El montaje USB varía por firmware. UIC Home puede bloquear la barra de notificaciones/selector USB en NEXGO compatible; haga la instalación antes del modo kiosco o mediante el menú de servicio.

6. Inscripción de prueba/debug

El registro contiene ID y secreto del dispositivo, cliente, serie del fabricante, época de asignación, prefijo de tópicos, servidor/puerto MQTT, URL HTTPS, certificado del servidor y clave bootstrap IoT. Trátelo como credencial.

Transfiéralo directamente al espacio privado usando run-as del paquete debug. Envíe el JSON por entrada estándar, no mediante argumentos ni almacenamiento compartido:

adb -s <serie-adb> shell run-as <paquete-instalado> sh -c 'cat > files/tms-enrollment.json'

Reinicie UIC Home. Cifra la inscripción con AndroidKeyStore y elimina la entrada en texto. Luego genera la clave privada IoT en AndroidKeyStore, obtiene/confirma el certificado y conecta MQTT. La primera conexión válida marca IoT aprovisionado y bloquea nuevas descargas de credenciales/certificados.

Solo en laboratorio USB local, restaure después de reiniciar:

adb -s <serie-adb> reverse tcp:18883 tcp:18883
adb -s <serie-adb> reverse tcp:15102 tcp:15102

Estos mapeos desaparecen al desconectar USB y no son diseño de producción.

7. Ajustes Android requeridos

1. Seleccione UIC Home como aplicación Inicio.
2. En UIC Home elija Permitir conexión con pantalla apagada y acepte la exención de optimización de batería.
3. Habilite UIC remote input en Accesibilidad para control remoto. La captura de pantalla todavía exige aprobación local en cada sesión.
4. Conceda ubicación solo si la política del cliente la requiere. Tener GPS no garantiza una señal en interiores.
5. Cambie el código de seis dígitos para Ajustes Android desde el predeterminado de desarrollo. No es el secreto del dispositivo.

Wi-Fi y Celular están dentro de Config de UIC Home sin ese código. Ajustes Android permanece protegido y en firmware compatible debe volver a la página de control remoto/ajustes sin exponer otras páginas.

8. Interacción con el portal

Verifique serie, marca/modelo, versiones Android/API y UIC Home, tiempo encendido, almacenamiento libre/total, memoria disponible/total, interfaces de red, IP pública observada, batería, capacidades e inventario de aplicaciones de usuario.

Las tareas incluyen solicitar estado, mensaje, reinicio, instalación específica por modelo, desinstalación excepto UIC Home, parámetros y asistencia remota. Los comandos pueden repetirse; UIC Home persiste el ID antes de ejecutar y reintenta su resultado hasta la confirmación SQL. En cola o Enviado no significa completado.

Los APK se descargan por HTTPS autenticado y se validan tamaño, SHA-256, paquete, versión y firma antes del SDK de marca. El portal actualiza inventario después de instalar/desinstalar. Se excluyen aplicaciones del sistema y sus actualizaciones.

El historial de ubicación agrega cambios de al menos 100 metros. Sin posición válida, un operador autorizado puede asignarla manualmente; una posición posterior reportada por el equipo prevalece.

9. Lista de aceptación

• Serie/cliente/modelo correctos y En línea con reporte reciente.
• Certificado IoT Aprovisionado y sin inscripción en texto.
• Paquete/versión correctos y UIC Home resuelto como Inicio.
• Conexión con pantalla apagada sin USB.
• Solicitar estado crea un reporte nuevo.
• Mensaje despierta pantalla y confirma solo al mostrarse.
• Reinicio regresa con nuevo reporte de arranque/uptime.
• Inventario coincide con el dispositivo.
• Vista/control remoto funciona después de aprobación local.
• Interfaz inglés/español sigue el idioma del dispositivo.

10. Solución de problemas