Zum Inhalt springen
Capgo

Getting Started

Dieser Inhalt ist in Ihrer Sprache noch nicht verfügbar.

  1. Install the package

    Terminal-Fenster
    npm i @capgo/capacitor-android-kiosk

  2. Sync with native projects

    Terminal-Fenster
    npx cap sync

Platform Support

This plugin is Android-only. For iOS kiosk mode functionality, please use the device’s built-in Guided Access feature.

Features

  • Kiosk Mode: Hide system UI and enter immersive fullscreen mode
  • Launcher Integration: Set your app as the device launcher/home app
  • Hardware Key Control: Block or allow specific hardware buttons
  • Status Detection: Check if kiosk mode is active or if app is set as launcher
  • Android 6.0+: Supports Android API 23 through Android 15 (API 35)

Basic Usage

Enter and Exit Kiosk Mode

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

Launcher Functionality

For full kiosk mode functionality, you need to set your app as the device 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);

Hardware Key Control

Control which hardware buttons are allowed to function 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({});

Complete Example

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 Reference

isInKioskMode()

Checks if the app is currently running in kiosk mode.

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

Returns:

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

isSetAsLauncher()

Checks if the app is set as the device launcher (home app).

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

Returns:

  • isLauncher (boolean): Whether the app is set as the device launcher

enterKioskMode()

Enters kiosk mode, hiding system UI and blocking hardware buttons. The app must be set as the device launcher for this to work effectively.

await CapacitorAndroidKiosk.enterKioskMode();

exitKioskMode()

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

await CapacitorAndroidKiosk.exitKioskMode();

setAsLauncher()

Opens the device’s home screen settings to allow user to set this app as the launcher. This is required for full kiosk mode functionality.

await CapacitorAndroidKiosk.setAsLauncher();

setAllowedKeys(options)

Sets which hardware keys are allowed to function in kiosk mode. By default, 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
});

Parameters:

  • volumeUp (boolean, optional): Allow volume up button (default: false)
  • volumeDown (boolean, optional): Allow volume down button (default: false)
  • back (boolean, optional): Allow back button (default: false)
  • home (boolean, optional): Allow home button (default: false)
  • recent (boolean, optional): Allow recent apps button (default: false)
  • power (boolean, optional): Allow power button (default: false)
  • camera (boolean, optional): Allow camera button if present (default: false)
  • menu (boolean, optional): Allow menu button if present (default: false)

getPluginVersion()

Get the native Capacitor plugin version.

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

Returns:

  • version (string): The plugin version number

Android Configuration

1. MainActivity Setup

To enable full hardware key blocking, you need to 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

Add launcher intent filter to make your app 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>

Important Notes

  1. Launcher Requirement: For full kiosk mode functionality (blocking home button, preventing task switching), your app must be set as the device launcher.

  2. Testing: When testing, you can exit kiosk mode programmatically or by setting another app as the launcher.

  3. Android Versions: The plugin uses modern Android APIs for Android 11+ and falls back to older methods for compatibility with Android 6.0+.

  4. Security: This plugin is designed for legitimate kiosk applications. Ensure you provide users with a way to exit kiosk mode.

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

iOS Alternative

For iOS devices, use the built-in Guided Access feature:

  1. Go to Settings > Accessibility > Guided Access
  2. Turn on Guided Access
  3. Set a passcode
  4. Open your app
  5. Triple-click the side button
  6. Adjust settings and start Guided Access

Best Practices

  1. Check launcher status 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 app 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
    }