Commencer

1. Installez le package

   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. Synchronisation avec les projets natifs

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Prise en charge de la plateforme

Ce plugin est Android uniquement. Pour la fonctionnalité du mode kiosque iOS, veuillez utiliser la fonction Accès guidé intégrée à l’appareil.

Fonctionnalités

• Mode kiosque : masquez l’interface utilisateur du système et passez en mode plein écran immersif
• Intégration du lanceur : définissez votre application comme lanceur d’appareil/application domestique
• Contrôle des touches matérielles : Bloquer ou autoriser des boutons matériels spécifiques
• Détection de statut : Vérifiez si le mode kiosque est actif ou si l’application est définie comme lanceur
• Android 6.0+ : prend en charge Android API 23 à Android 15 (API 35)

Utilisation de base

Entrer et quitter le mode kiosque

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);

Fonctionnalité du lanceur

Pour bénéficier des fonctionnalités complètes du mode kiosque, vous devez définir votre application comme lanceur d’appareil :

// 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);

Contrôle des clés matérielles

Contrôlez quels boutons matériels sont autorisés à fonctionner en mode kiosque :

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

// Block all keys (default)
await CapacitorAndroidKiosk.setAllowedKeys({});

Exemple complet

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);
  }
}

API Référence

estInKioskMode()

Vérifie si l’application s’exécute actuellement en mode kiosque.

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

Retours :

• isInKioskMode (booléen) : indique si le mode kiosque est actuellement actif

---

isSetAsLauncher()

Vérifie si l’application est définie comme lanceur d’appareil (application domestique).

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

Retours :

• isLauncher (booléen) : indique si l’application est définie comme lanceur de périphérique

---

enterKioskMode()

Passe en mode kiosque, masquant l’interface utilisateur du système et bloquant les boutons matériels. L’application doit être définie comme lanceur d’appareil pour que cela fonctionne efficacement.

await CapacitorAndroidKiosk.enterKioskMode();

---

quitterKioskMode()

Quitte le mode kiosque, rétablissant la fonctionnalité normale de l’interface utilisateur du système et des boutons matériels.

await CapacitorAndroidKiosk.exitKioskMode();

---

setAsLauncher()

Ouvre les paramètres de l’écran d’accueil de l’appareil pour permettre à l’utilisateur de définir cette application comme lanceur. Ceci est requis pour la fonctionnalité complète du mode kiosque.

await CapacitorAndroidKiosk.setAsLauncher();

---

setAllowedKeys (options)

Définit les touches matérielles autorisées à fonctionner en mode kiosque. Par défaut, toutes les clés matérielles sont bloquées en mode kiosque.

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

Paramètres :

• volumeUp (booléen, facultatif) : Autoriser le bouton d’augmentation du volume (par défaut : faux)
• volumeDown (booléen, facultatif) : Autoriser le bouton de réduction du volume (par défaut : faux)
• back (booléen, facultatif) : Autoriser le bouton Retour (par défaut : false)
• home (booléen, facultatif) : Autoriser le bouton d’accueil (par défaut : faux)
• recent (booléen, facultatif) : bouton Autoriser les applications récentes (par défaut : false)
• power (booléen, facultatif) : Autoriser le bouton d’alimentation (par défaut : faux)
• camera (booléen, facultatif) : Autoriser le bouton de la caméra s’il est présent (par défaut : faux)
• menu (booléen, facultatif) : Autoriser le bouton de menu s’il est présent (par défaut : faux)

---

###getPluginVersion()

Obtenez la version native du plugin Capacitor.

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

Retours :

• version (string) : Le numéro de version du plugin

AndroidConfiguration

1. Configuration de l’activité principale

Pour activer le blocage complet des clés matérielles, vous devez remplacer dispatchKeyEvent dans votre 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

Ajoutez un filtre d'intention de lanceur pour rendre votre application sélectionnable en tant que lanceur :

```xml
<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>

Remarques importantes

1. Exigence du lanceur : pour bénéficier d’une fonctionnalité complète du mode kiosque (blocage du bouton d’accueil, empêchement du changement de tâche), votre application doit être définie comme lanceur d’appareil.

2. Test : lors des tests, vous pouvez quitter le mode kiosque par programme ou en définissant une autre application comme lanceur.

3. Android Versions : Le plugin utilise des API Android modernes pour Android 11+ et revient à des méthodes plus anciennes pour la compatibilité avec Android 6.0+.

4. Sécurité : ce plugin est conçu pour les applications de kiosque légitimes. Assurez-vous de fournir aux utilisateurs un moyen de quitter le mode kiosque.

5. Batterie : le mode kiosque maintient l’écran allumé. Pensez à mettre en œuvre votre propre gestion du délai d’attente de l’écran ou de la luminosité.

iOS Alternative

Pour les appareils iOS, utilisez la fonctionnalité intégrée Accès guidé :

1. Accédez à Paramètres > Accessibilité > Accès guidé
2. Activez l’accès guidé
3. Définir un mot de passe
4. Ouvrez votre application
5. Triple-cliquez sur le bouton latéral
6. Ajustez les paramètres et démarrez l’accès guidé

## meilleures pratiques

1. Vérifiez d’abord l’état du lanceur

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

2. Fournir un mécanisme de sortie

   // 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. Gérer le cycle de vie des applications

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

4. Gestion des erreurs

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