capacitor-android-kiosk

Lock an Android device into kiosk mode from your Capacitor app: hide system UI, block hardware buttons and run as the home launcher. Built for point of sale, signage and single-purpose devices.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-android-kiosk in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-android-kiosk to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Kiosk mode: enterKioskMode() hides system UI and blocks hardware buttons, exitKioskMode() restores them.
• Launcher: setAsLauncher() opens home screen settings so your app can become the launcher, isSetAsLauncher() checks it.
• Allowed keys: setAllowedKeys() picks which hardware keys keep working in kiosk mode.
• State check: isInKioskMode() reports whether kiosk mode is active.
• Platforms: Android. Android only. iOS and web are not supported.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/android-kiosk/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-android-kiosk` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-android-kiosk
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
• Keep-alive: Foreground service while in kiosk; stopped when you call exitKioskMode().
• Session options: restoreAfterReboot tries to opens the app again after reboot; relaunch + relaunchIntervalMinutes tries to bring the UI forward on a timer.
• 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)

Usage

Basic Kiosk Mode

import { CapacitorAndroidKiosk } from '@capgo/capacitor-android-kiosk';

// Enter kiosk mode (with optional: restoreAfterReboot, relaunch, relaunchIntervalMinutes)
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

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

• isInKioskMode()
• isSetAsLauncher()
• enterKioskMode(...)
• exitKioskMode()
• setAsLauncher()
• setAllowedKeys(...)
• getPluginVersion()
• Interfaces

Capacitor Android Kiosk Plugin for controlling kiosk mode and launcher functionality. This plugin is Android-only. For iOS kiosk mode, use the device's Guided Access feature.

isInKioskMode()

isInKioskMode() => Promise<{ isInKioskMode: boolean; }>

Checks if the app is currently running in kiosk mode.

Returns: Promise<{ isInKioskMode: boolean; }>

Since: 1.0.0

isSetAsLauncher()

isSetAsLauncher() => Promise<{ isLauncher: boolean; }>

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

Returns: Promise<{ isLauncher: boolean; }>

Since: 1.0.0

enterKioskMode(...)

enterKioskMode(options?: EnterKioskModeOptions | undefined) => Promise<void>

Enters kiosk mode, hiding system UI and blocking hardware buttons. Also starts a foreground keep-alive service so the app is less likely to be killed by the system. The app must be set as the device launcher for this to work effectively.

Since: 1.0.0

exitKioskMode()

exitKioskMode() => Promise<void>

Exits kiosk mode, restoring normal system UI and hardware button functionality. Also stops the foreground keep-alive service started in enterKioskMode().

Since: 1.0.0

setAsLauncher()

setAsLauncher() => Promise<void>

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.

Since: 1.0.0

setAllowedKeys(...)

setAllowedKeys(options: AllowedKeysOptions) => Promise<void>

Sets which hardware keys are allowed to function in kiosk mode. By default, all hardware keys are blocked in kiosk mode.

Since: 1.0.0

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Interfaces

EnterKioskModeOptions

Optional flags for enterKioskMode.

AllowedKeysOptions

Configuration options for allowed hardware keys in kiosk mode.

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

Contributing

See CONTRIBUTING.md

License

MIT

Author

Martin Donadieu [email protected]