kiosk-webview-template

Plantilla Android (Java) que convierte cualquier aplicación web en una app nativa en modo kiosko: pantalla completa bloqueada, sin barras del sistema, sin navegación fuera del WebView y pensada para correr en dispositivos dedicados (tótems, exhibidores, puntos de venta, pantallas informativas).

Cambiás una URL, personalizás el icono y ya tenés tu kiosko empaquetado como APK.

Tabla de Contenidos

¿Por qué kiosk-webview-template?
Características
Requisitos del Sistema
Permisos
Quick Start
Configuración de tu WebApp
Configuración del Proyecto
Estructura del Código
Comportamiento sin Internet
Construcción y Despliegue
Personalización Avanzada
Casos de Uso
Pruebas
Roadmap
Versión
Licencia

¿Por qué kiosk-webview-template?

Armar un kiosko Android real no es solo "abrir un WebView en fullscreen". Requiere bloquear barras del sistema, controlar gestos, manejar reconexión, evitar que el usuario salga de la app accidentalmente y, sobre todo, no reinventar la rueda cada vez que necesitás un exhibidor nuevo.

Esta plantilla te da:

Un punto de partida probado y mínimo para apps kiosko.
Cero lógica de negocio: toda la UI vive en tu webapp, vos solo definís la URL.
Personalización por configuración, no por reescritura: orientación, touch, zoom, certificados, etc.
Base lista para endurecer (lock task mode, Device Owner, MDM) cuando lo necesites.

Características

Modo Kiosko (núcleo del proyecto)

Pantalla completa inmersiva (sticky immersive): oculta barras de estado y navegación.
Bloqueo del back del sistema fuera del WebView (la app no se cierra con el botón atrás).
Entrada solo por mouse por defecto — el touch queda deshabilitado, ideal para exhibidores con mouse externo.
Cierre protegido mediante clic derecho del mouse (comportamiento por defecto, modificable).
Recarga automática al volver al primer plano, sin intervención del usuario.
Caché optimizado para evitar pantallas en blanco al reanudar.
Orientación bloqueada (portrait por defecto, configurable a landscape).

WebView embebido

URL configurable desde una única constante en MainActivity.java.
Soporte HTTPS y HTTP claro para entornos de desarrollo.
Carga de assets locales empaquetados en el APK (file:///android_asset/).
JavaScript, DOM storage y base de datos web habilitados.
DevTools remoto activable en builds de debug para inspeccionar la webapp desde Chrome.

Resiliencia

Detección de conexión en tiempo real.
Reconexión automática cada 3 segundos cuando no hay red.
Pantalla de error amigable con animación de carga y mensaje visual.
Gestión de memoria del WebView para evitar memory leaks en sesiones largas.
Manejo correcto del ciclo de vida (onPause / onResume / onDestroy).

Requisitos del Sistema

Componente	Versión / Detalle
Mínimo SDK	Android 7.0 Nougat (API 24)
Target SDK	Android 14 (API 36)
Compile SDK	36
Java	11
Build Tool	Android Studio + Gradle
Permisos	`INTERNET`, `ACCESS_NETWORK_STATE`

Permisos

Declarados en app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Para endurecer el modo kiosko en producción (lock task mode, Device Owner) probablemente necesites permisos adicionales. Ver Personalización Avanzada.

Quick Start

# 1. Clonar el repositorio
git clone https://github.com/tu-usuario/kiosk-webview-template.git
cd kiosk-webview-template

# 2. Abrir en Android Studio
#    File → Open → seleccionar la carpeta del proyecto

# 3. Configurar tu URL
#    Editar MainActivity.java:
#    private final String url = "https://tu-kiosko.com";

# 4. Compilar e instalar
./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk

Eso es todo. Tu kiosko está corriendo en el dispositivo.

Configuración de tu WebApp

1. Definir la URL objetivo

Abrí app/src/main/java/com/example/webapp/MainActivity.java y cambiá la constante:

private final String url = "https://tu-dominio.com";

Ejemplos válidos:

// Producción (kiosko en local con tu webapp)
private final String url = "https://kiosko.miapp.com";

// Desarrollo local en emulador
private final String url = "http://10.0.2.2:3000";

// Desarrollo local en dispositivo físico (vía adb reverse)
private final String url = "http://localhost:3000";

// Asset local empaquetado en el APK
private final String url = "file:///android_asset/index.html";

// Con puerto y path específicos
private final String url = "https://api.miapp.com:8443/kiosk";

2. Nombre visible del kiosko

Editá app/src/main/res/values/strings.xml:

<string name="app_name">Kiosko - Mi Empresa</string>

3. Icono del kiosko

Reemplazá los archivos en app/src/main/res/mipmap-*/ con tus propios assets:

ic_launcher.png
ic_launcher_round.png

Tip: usá Image Asset Studio (clic derecho en res → New → Image Asset) para generar todas las densidades automáticamente.

4. Package name (opcional)

Si querés renombrar el paquete, usá Refactor → Rename en Android Studio sobre el paquete com.example.webapp, y actualizá applicationId y namespace en build.gradle.kts.

Configuración del Proyecto

Identidad de la aplicación

Modificá estos valores en app/build.gradle.kts:

namespace = "com.example.webapp"
applicationId = "com.example.webapp"
versionCode = 1
versionName = "1.0"

Dependencias principales

androidx.appcompat:appcompat
com.google.android.material:material
junit:junit (testing unitario)
androidx.test.ext:junit + espresso-core (testing instrumentado)

Estructura del Código

kiosk-webview-template/
├── app/
│   ├── src/
│   │   ├── main/
│   │   │   ├── AndroidManifest.xml
│   │   │   ├── java/com/example/webapp/
│   │   │   │   └── MainActivity.java      # Lógica del WebView y modo kiosko
│   │   │   └── res/
│   │   │       ├── layout/                # activity_main.xml
│   │   │       ├── values/                # strings.xml, colors.xml, themes.xml
│   │   │       ├── values-night/          # tema oscuro
│   │   │       └── mipmap-*/              # iconos
│   │   └── test/                          # tests unitarios e instrumentados
│   └── build.gradle.kts
├── build.gradle.kts
└── README.md

MainActivity.java

Punto de entrada único. Responsabilidades:

Inflar el layout con el WebView.
Configurar flags de pantalla completa e inmersión.
Habilitar JavaScript, DOM storage y base de datos web.
Registrar listeners de conectividad y manejar la reconexión.
Manejar ciclo de vida (onPause / onResume / onDestroy).
Gestionar navegación interna y eventos de mouse.

Comportamiento sin Internet

Cuando el dispositivo no tiene conexión:

Se oculta el WebView y se muestra una vista de error.
Aparece un mensaje de advertencia visual y una animación de carga giratoria.
Un handler reintenta la conexión cada 3 segundos.
Al establecerse la red, la app recarga la URL automáticamente.

Pensado para kioskos unattended: el dispositivo se recupera solo, sin intervención humana.

Construcción y Despliegue

Compilar APK Debug

./gradlew assembleDebug

Salida: app/build/outputs/apk/debug/app-debug.apk

Compilar APK Release

./gradlew assembleRelease

Por defecto, el build.gradle.kts usa la firma de debug para el build de release. Antes de publicar en Play Store configurá un keystore propio en signingConfigs.

Instalar en dispositivo

adb install -r app/build/outputs/apk/debug/app-debug.apk

Instalación silenciosa en múltiples dispositivos (kioskos)

adb devices | tail -n +2 | cut -sf1 | xargs -I{} adb -s {} install -r app-debug.apk

Limpiar build

./gradlew clean

Personalización Avanzada

Cambiar orientación

En AndroidManifest.xml, dentro de la actividad:

android:screenOrientation="landscape"  <!-- o "portrait", "sensor", "nosensor" -->

Habilitar entrada táctil

En MainActivity.java, comentá o eliminá la línea que deshabilita el touch:

// webView.setOnTouchListener((v, event) -> true);

Permitir tráfico HTTP en producción

Para mantener tráfico claro hacia un dominio específico, ajustá network_security_config.xml con un domain-config apropiado.

Habilitar zoom y pinch

Por defecto el zoom está deshabilitado para una experiencia kiosko controlada. Para rehabilitarlo en MainActivity.java:

webView.getSettings().setBuiltInZoomControls(true);
webView.getSettings().setSupportZoom(true);

Habilitar DevTools remoto

Útil para depurar la webapp desde Chrome en escritorio:

WebView.setWebContentsDebuggingEnabled(true);

Activá esto solo en builds de debug.

Endurecer el modo kiosko (avanzado)

Para un kiosko real (que el usuario no pueda evadir), necesitás ir más allá de la UI:

Lock Task Mode (startLockTask()): requiere que la app sea Device Owner o que se lance desde un launcher en modo kiosko.
Device Owner: configurá la app como propietaria del dispositivo vía adb shell dpm set-device-owner.
Quitar barras del sistema de forma agresiva: combinar WindowInsetsController + flags legacy.
Deshabilitar botones físicos: requiere permisos de sistema o root.

Estos cambios están fuera del scope de esta plantilla base, pero son los próximos pasos naturales si necesitás un kiosko unattended de producción.

Casos de Uso

Tótems y exhibidores en puntos de venta mostrando catálogo, promociones o encuestas.
Pantallas informativas en recepciones, salas de espera o ferias.
Demos de producto en stands, corriendo 24/7 sin intervención.
Kioskos de auto-consulta (turnos, trámites, información).
Displays de cartelería digital (digital signage) alimentados desde una webapp.
Equipos dedicados en líneas de producción o backoffice que necesitan una UI web simple y bloqueada.

Pruebas

El proyecto incluye el esqueleto estándar de Android Studio:

Tests unitarios locales: app/src/test/
Tests instrumentados: app/src/test/androidTest/

Ejecutar:

./gradlew test              # unitarios
./gradlew connectedAndroidTest   # instrumentados (requiere dispositivo/emulador)

Roadmap

Soporte opcional para Lock Task Mode / Device Owner out-of-the-box.
Configuración de kiosko vía Intent extras o archivo assets/kiosk.json (sin recompilar).
Plantilla de página offline personalizable.
Soporte para wake lock configurable (mantener pantalla siempre encendida).
Documentación de despliegue a flotas con MDM (Google Workspace, Knox, etc.).
Script Gradle para build multi-flavor (varios kioskos desde un mismo proyecto).

Versión

Versión actual: 1.0
Version code: 1

Licencia

Este proyecto se distribuye como plantilla de código abierto bajo licencia MIT. Adaptalo libremente a las necesidades de tu kiosko o producto.

Name		Name	Last commit message	Last commit date
.idea		.idea
app		app
gradle		gradle
.gitignore		.gitignore
README.md		README.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

Latest commit

History

Folders and files

Repository files navigation