Primeros pasos

1. Instalar El Paquete
   npm

   npm i @Capgo/Capacitor-android-kiosk

   pnpm

   pnpm add @Capgo/Capacitor-android-kiosk

   yarn

   yarn add @Capgo/Capacitor-android-kiosk

   bun

   bun add @Capgo/Capacitor-android-kiosk

2. Sync with native projects
   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Este Plugin is Android-only. For iOS kiosk mode functionality, please Usar El Dispositivo’s built-in Guided Access feature.

• Kiosk Mode: Hide system UI and enter immersive fullscreen mode
• Launcher Integración: Establecer your Aplicación as El Dispositivo launcher/home Aplicación
• Hardware Key Control: Block or allow specific hardware buttons
• Estado Detection: Verificar if kiosk mode is active or if Aplicación is Establecer as launcher
• Android 6.0+: Supports Android API 23 through Android 15 (API 35)

import { CapacitorAndroidKiosk } from '@capgo/capacitor-android-kiosk';
// Enter kiosk mode
await CapacitorAndroidKiosk.enterKioskMode();
// Exit kiosk mode
await CapacitorAndroidKiosk.exitKioskMode();
// Check if in kiosk mode
const { isInKioskMode } = await CapacitorAndroidKiosk.isInKioskMode();
console.log('Kiosk mode active:', isInKioskMode);

For full kiosk mode functionality, Necesita A Establecer your Aplicación as El Dispositivo launcher:

// Open home screen settings for user to select your app as launcher
await CapacitorAndroidKiosk.setAsLauncher();
// Check if app is set as launcher
const { isLauncher } = await CapacitorAndroidKiosk.isSetAsLauncher();
console.log('App is launcher:', isLauncher);

Control which hardware buttons are allowed A Función in kiosk mode:

// Allow only volume keys
await CapacitorAndroidKiosk.setAllowedKeys({
volumeUp: true,
volumeDown: true,
back: false,
home: false,
recent: false
});
// Block all keys (default)
await CapacitorAndroidKiosk.setAllowedKeys({});

async function setupKioskMode() {
try {
// Check if already set as launcher
const { isLauncher } = await CapacitorAndroidKiosk.isSetAsLauncher();
if (!isLauncher) {
// Prompt user to set as launcher
await CapacitorAndroidKiosk.setAsLauncher();
alert('Please select this app as your Home app');
return;
}
// Configure allowed keys
await CapacitorAndroidKiosk.setAllowedKeys({
volumeUp: true,
volumeDown: true,
back: false,
home: false,
recent: false,
power: false
});
// Enter kiosk mode
await CapacitorAndroidKiosk.enterKioskMode();
console.log('Kiosk mode activated');
} catch (error) {
console.error('Failed to setup kiosk mode:', error);
}
}

Checks if El Aplicación is currently Ejecutando in kiosk mode.

const { isInKioskMode } = await CapacitorAndroidKiosk.isInKioskMode();

Returns:

• isInKioskMode (boolean): Whether kiosk mode is currently active

---

isSetAsLauncher()

Checks if El Aplicación is Establecer as El Dispositivo launcher (home Aplicación).

const { isLauncher } = await CapacitorAndroidKiosk.isSetAsLauncher();

Returns:

• isLauncher (boolean): Whether El Aplicación is Establecer as El Dispositivo launcher

---

enterKioskMode()

Enters kiosk mode, hiding system UI and blocking hardware buttons. El Aplicación Debe be Establecer as El Dispositivo launcher for this A work effectively.

await CapacitorAndroidKiosk.enterKioskMode();

---

exitKioskMode()

Exits kiosk mode, restoring normal system UI and hardware button functionality.

await CapacitorAndroidKiosk.exitKioskMode();

---

setAsLauncher()

Opens El Dispositivo’s home screen Configuración A allow user A Establecer this Aplicación as El launcher. Esto es Requerido for full kiosk mode functionality.

await CapacitorAndroidKiosk.setAsLauncher();

---

setAllowedKeys(Opciones)

Sets which hardware keys are allowed A Función in kiosk mode. By Predeterminado, all hardware keys are blocked in kiosk mode.

await CapacitorAndroidKiosk.setAllowedKeys({
  volumeUp: true,
  volumeDown: true,
  back: false,
  home: false,
  recent: false,
  power: false,
  camera: false,
  menu: false
});

Parámetros:

• volumeUp (boolean, Opcional): Allow volume up button (Predeterminado: false)
• volumeDown (boolean, Opcional): Allow volume down button (Predeterminado: false)
• back (boolean, Opcional): Allow back button (Predeterminado: false)
• home (boolean, Opcional): Allow home button (Predeterminado: false)
• recent (boolean, Opcional): Allow recent Aplicaciones button (Predeterminado: false)
• power (boolean, Opcional): Allow power button (Predeterminado: false)
• camera (boolean, Opcional): Allow camera button if present (Predeterminado: false)
• menu (boolean, Opcional): Allow menu button if present (Predeterminado: false)

---

getPluginVersion()

Get El native Capacitor Plugin Versión.

const { version } = await CapacitorAndroidKiosk.getPluginVersion();
console.log('Plugin version:', version);

Returns:

• version (string): El Plugin Versión number

Android Configuración

1. MainActivity Configuración

Para habilitar full hardware key blocking, Necesita A override dispatchKeyEvent in your MainActivity.java:

import android.view.KeyEvent;
import ee.forgr.plugin.android_kiosk.CapacitorAndroidKioskPlugin;

public class MainActivity extends BridgeActivity {
    @Override
    public boolean dispatchKeyEvent(KeyEvent event) {
        // Get the kiosk plugin
        CapacitorAndroidKioskPlugin kioskPlugin = (CapacitorAndroidKioskPlugin)
            this.getBridge().getPlugin("CapacitorAndroidKiosk").getInstance();

        if (kioskPlugin != null && kioskPlugin.shouldBlockKey(event.getKeyCode())) {
            return true; // Block the key
        }

        return super.dispatchKeyEvent(event);
    }

    @Override
    public void onBackPressed() {
        // Don't call super.onBackPressed() to disable back button
        // Or call the plugin's handleOnBackPressed
    }
}

2. AndroidManifest.XML

Agregar launcher intent filter A make your Aplicación selectable as a launcher:

<activity
    android:name=".MainActivity"
    ...>

    <!-- Existing intent filter -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <!-- Add this to make app selectable as launcher -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.HOME" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Importante Notas

1. Launcher Requirement: For full kiosk mode functionality (blocking home button, preventing task switching), your Aplicación Debe be Establecer as El Dispositivo launcher.

2. Pruebas: When Pruebas, Puede exit kiosk mode programmatically or by setting another Aplicación as El launcher.

3. Android Versiones: El Plugin uses modern Android APIs for Android 11+ and falls back A older Métodos for compatibility with Android 6.0+.

4. Seguridad: Este Plugin is designed for legitimate kiosk applications. Ensure you provide users with a way A exit kiosk mode.

5. Battery: Kiosk mode keeps El screen on. Consider implementing your own screen timeout or brightness management.

iOS Alternative

For iOS Dispositivos, Usar El built-in Guided Access feature:

1. Go A Configuración > Accessibility > Guided Access
2. Turn on Guided Access
3. Establecer a passcode
4. Open your Aplicación
5. Triple-Haga clic El side button
6. Adjust Configuración and start Guided Access

Best Practices

1. Verificar launcher Estado first

   const { isLauncher } = await CapacitorAndroidKiosk.isSetAsLauncher();
   if (!isLauncher) {
     // Prompt user to set as launcher first
     await CapacitorAndroidKiosk.setAsLauncher();
   }

2. Provide exit mechanism

   // Allow specific key combination to exit
   // Or implement a secret gesture/pattern
   async function exitKioskWithConfirmation() {
     const confirmed = confirm('Exit kiosk mode?');
     if (confirmed) {
       await CapacitorAndroidKiosk.exitKioskMode();
     }
   }

3. Handle Aplicación lifecycle

   // Re-enter kiosk mode when app resumes
   window.addEventListener('resume', async () => {
     const { isInKioskMode } = await CapacitorAndroidKiosk.isInKioskMode();
     if (!isInKioskMode) {
       await CapacitorAndroidKiosk.enterKioskMode();
     }
   });

4. Error handling

   try {
     await CapacitorAndroidKiosk.enterKioskMode();
   } catch (error) {
     console.error('Failed to enter kiosk mode:', error);
     // Notify user and provide alternative
   }