@gachlab/capacitor-kiosk

A Capacitor plugin for Android kiosk mode using the Lock Task API. Pin your app to the screen and prevent users from leaving.

Android only. Web stub returns false / throws errors.

Installation

npm install @gachlab/capacitor-kiosk
npx cap sync

Prerequisites

For kiosk mode to work, your app must be set as a device owner or the activity must be whitelisted for lock task mode. Without this, enterKioskMode() will reject with a SecurityException.

To set your app as device owner (on a factory-reset device):

adb shell dpm set-device-owner com.your.package/.MainActivity

Usage

import { KioskMode } from '@gachlab/capacitor-kiosk';

// Check if currently in kiosk mode
const { value } = await KioskMode.isInKioskMode();

// Enter kiosk mode
await KioskMode.enterKioskMode();

// Exit kiosk mode
await KioskMode.exitKioskMode();

// Toggle kiosk mode
await KioskMode.toggleKioskMode();

API

isInKioskMode()

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

Returns whether the device is currently in lock task (kiosk) mode.

enterKioskMode()

enterKioskMode() => Promise<void>

Enters kiosk mode. Rejects with an error if the app is not a device owner or the activity is not whitelisted.

exitKioskMode()

exitKioskMode() => Promise<void>

Exits kiosk mode. Rejects with an error if the app is not a device owner.

toggleKioskMode()

toggleKioskMode() => Promise<void>

Toggles kiosk mode based on the current state.

addListener('kioskEntered', ...)

addListener(
  eventName: 'kioskEntered',
  listenerFunc: (event: { timestamp: number }) => void,
) => Promise<PluginListenerHandle>

Fires when the app enters kiosk (lock task) mode. timestamp is the epoch time in milliseconds.

addListener('kioskExited', ...)

addListener(
  eventName: 'kioskExited',
  listenerFunc: (event: { reason: 'user' | 'system' | 'api'; timestamp: number }) => void,
) => Promise<PluginListenerHandle>

Fires when the app leaves kiosk mode. reason is 'api' when triggered by exitKioskMode(), or 'user' when the exit is detected on the next foreground.

Android does not push lock-task changes to normal apps, so a user/system exit performed while the app is backgrounded is only detected when the activity next resumes (latency). Real-time detection requires the app to be Device Owner; 'system' is reserved for that future detector.

Migration from v1

v2 is a breaking change due to the Capacitor 5 → 8 upgrade:

• Requires Capacitor 8+ (@capacitor/core ^8.0.1)
• Requires Android SDK 36, minSdk 24, Java 21
• Package moved from cc.elysium.capacitor.plugin.kiosk to com.gachlab.capacitor.kiosk
• Web stub now returns { value: false } instead of { value: true }
• Web stub now throws errors for enter/exit/toggle instead of silently succeeding
• SecurityException is now caught and returned as a rejected promise instead of crashing