@capgo/capacitor-android-kiosk 7.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Martin Donadieu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,340 @@
+# @capgo/capacitor-android-kiosk
+
+Android Kiosk Mode plugin for Capacitor - Lock device into kiosk mode with launcher functionality
+
+## Install
+
+```bash
+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](https://support.apple.com/en-us/HT202612) 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)
+
+## Usage
+
+### Basic Kiosk Mode
+
+```typescript
+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:
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+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
+
+<docgen-index>
+
+* [`isInKioskMode()`](#isinkioskmode)
+* [`isSetAsLauncher()`](#issetaslauncher)
+* [`enterKioskMode()`](#enterkioskmode)
+* [`exitKioskMode()`](#exitkioskmode)
+* [`setAsLauncher()`](#setaslauncher)
+* [`setAllowedKeys(...)`](#setallowedkeys)
+* [`getPluginVersion()`](#getpluginversion)
+* [Interfaces](#interfaces)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+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()
+
+```typescript
+isInKioskMode() => Promise<{ isInKioskMode: boolean; }>
+```
+
+Checks if the app is currently running in kiosk mode.
+
+**Returns:** <code>Promise&lt;{ isInKioskMode: boolean; }&gt;</code>
+
+**Since:** 1.0.0
+
+--------------------
+
+
+### isSetAsLauncher()
+
+```typescript
+isSetAsLauncher() => Promise<{ isLauncher: boolean; }>
+```
+
+Checks if the app is set as the device launcher (home app).
+
+**Returns:** <code>Promise&lt;{ isLauncher: boolean; }&gt;</code>
+
+**Since:** 1.0.0
+
+--------------------
+
+
+### enterKioskMode()
+
+```typescript
+enterKioskMode() => Promise<void>
+```
+
+Enters kiosk mode, hiding system UI and blocking hardware buttons.
+The app must be set as the device launcher for this to work effectively.
+
+**Since:** 1.0.0
+
+--------------------
+
+
+### exitKioskMode()
+
+```typescript
+exitKioskMode() => Promise<void>
+```
+
+Exits kiosk mode, restoring normal system UI and hardware button functionality.
+
+**Since:** 1.0.0
+
+--------------------
+
+
+### setAsLauncher()
+
+```typescript
+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(...)
+
+```typescript
+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.
+
+| Param         | Type                                                              | Description                    |
+| ------------- | ----------------------------------------------------------------- | ------------------------------ |
+| **`options`** | <code><a href="#allowedkeysoptions">AllowedKeysOptions</a></code> | Configuration for allowed keys |
+
+**Since:** 1.0.0
+
+--------------------
+
+
+### getPluginVersion()
+
+```typescript
+getPluginVersion() => Promise<{ version: string; }>
+```
+
+Get the native Capacitor plugin version.
+
+**Returns:** <code>Promise&lt;{ version: string; }&gt;</code>
+
+**Since:** 1.0.0
+
+--------------------
+
+
+### Interfaces
+
+
+#### AllowedKeysOptions
+
+Configuration options for allowed hardware keys in kiosk mode.
+
+| Prop             | Type                 | Description                      | Default            |
+| ---------------- | -------------------- | -------------------------------- | ------------------ |
+| **`volumeUp`**   | <code>boolean</code> | Allow volume up button           | <code>false</code> |
+| **`volumeDown`** | <code>boolean</code> | Allow volume down button         | <code>false</code> |
+| **`back`**       | <code>boolean</code> | Allow back button                | <code>false</code> |
+| **`home`**       | <code>boolean</code> | Allow home button                | <code>false</code> |
+| **`recent`**     | <code>boolean</code> | Allow recent apps button         | <code>false</code> |
+| **`power`**      | <code>boolean</code> | Allow power button               | <code>false</code> |
+| **`camera`**     | <code>boolean</code> | Allow camera button (if present) | <code>false</code> |
+| **`menu`**       | <code>boolean</code> | Allow menu button (if present)   | <code>false</code> |
+
+</docgen-api>
+
+## Android Configuration
+
+### 1. MainActivity Setup
+
+To enable full hardware key blocking, you need to override `dispatchKeyEvent` in your `MainActivity.java`:
+
+```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:
+
+```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>
+```
+
+## 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](https://support.apple.com/en-us/HT202612) 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](CONTRIBUTING.md)
+
+## License
+
+MIT
+
+## Author
+
+Martin Donadieu <martin@capgo.app>

package/android/build.gradle

@@ -0,0 +1,59 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.2.1'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.6.1'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
+}
+
+buildscript {
+    repositories {
+        mavenCentral()
+        google()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.7.2'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace "ee.forgr.plugin.android_kiosk"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    jcenter()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/ee/forgr/plugin/android_kiosk/CapacitorAndroidKioskPlugin.java

@@ -0,0 +1,283 @@
+package ee.forgr.plugin.android_kiosk;
+
+import android.app.Activity;
+import android.app.ActivityManager;
+import android.content.ComponentName;
+import android.content.Context;
+import android.content.Intent;
+import android.content.pm.PackageManager;
+import android.os.Build;
+import android.view.KeyEvent;
+import android.view.View;
+import android.view.WindowManager;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import java.util.HashSet;
+import java.util.Set;
+
+@CapacitorPlugin(name = "CapacitorAndroidKiosk")
+public class CapacitorAndroidKioskPlugin extends Plugin {
+
+    private final String pluginVersion = "1.0.0";
+    private boolean isInKioskMode = false;
+    private final Set<Integer> allowedKeys = new HashSet<>();
+
+    @Override
+    public void load() {
+        // Initialize with no allowed keys by default
+        allowedKeys.clear();
+    }
+
+    @PluginMethod
+    public void isInKioskMode(PluginCall call) {
+        JSObject ret = new JSObject();
+        ret.put("isInKioskMode", isInKioskMode);
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void isSetAsLauncher(PluginCall call) {
+        JSObject ret = new JSObject();
+        boolean isLauncher = checkIfLauncher();
+        ret.put("isLauncher", isLauncher);
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void enterKioskMode(PluginCall call) {
+        try {
+            Activity activity = getActivity();
+            if (activity == null) {
+                call.reject("Activity not available");
+                return;
+            }
+
+            activity.runOnUiThread(() -> {
+                try {
+                    View decorView = activity.getWindow().getDecorView();
+
+                    // Hide system UI for different Android versions
+                    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                        // Android 11+ (API 30+)
+                        activity.getWindow().setDecorFitsSystemWindows(false);
+                        android.view.WindowInsetsController controller = decorView.getWindowInsetsController();
+                        if (controller != null) {
+                            controller.hide(android.view.WindowInsets.Type.statusBars() | android.view.WindowInsets.Type.navigationBars());
+                            controller.setSystemBarsBehavior(android.view.WindowInsetsController.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE);
+                        }
+                    } else {
+                        // Android 10 and below
+                        int uiOptions =
+                            View.SYSTEM_UI_FLAG_LAYOUT_STABLE |
+                            View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION |
+                            View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN |
+                            View.SYSTEM_UI_FLAG_HIDE_NAVIGATION |
+                            View.SYSTEM_UI_FLAG_FULLSCREEN |
+                            View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY;
+                        decorView.setSystemUiVisibility(uiOptions);
+                    }
+
+                    // Keep screen on
+                    activity.getWindow().addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
+
+                    // Prevent status bar from being pulled down
+                    activity.getWindow().addFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN);
+
+                    isInKioskMode = true;
+                    call.resolve();
+                } catch (Exception e) {
+                    call.reject("Failed to enter kiosk mode", e);
+                }
+            });
+        } catch (Exception e) {
+            call.reject("Failed to enter kiosk mode", e);
+        }
+    }
+
+    @PluginMethod
+    public void exitKioskMode(PluginCall call) {
+        try {
+            Activity activity = getActivity();
+            if (activity == null) {
+                call.reject("Activity not available");
+                return;
+            }
+
+            activity.runOnUiThread(() -> {
+                try {
+                    View decorView = activity.getWindow().getDecorView();
+
+                    // Restore system UI for different Android versions
+                    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                        // Android 11+ (API 30+)
+                        activity.getWindow().setDecorFitsSystemWindows(true);
+                        android.view.WindowInsetsController controller = decorView.getWindowInsetsController();
+                        if (controller != null) {
+                            controller.show(android.view.WindowInsets.Type.statusBars() | android.view.WindowInsets.Type.navigationBars());
+                        }
+                    } else {
+                        // Android 10 and below
+                        decorView.setSystemUiVisibility(View.SYSTEM_UI_FLAG_VISIBLE);
+                    }
+
+                    // Clear screen on flag
+                    activity.getWindow().clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
+
+                    // Clear fullscreen flag
+                    activity.getWindow().clearFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN);
+
+                    isInKioskMode = false;
+                    call.resolve();
+                } catch (Exception e) {
+                    call.reject("Failed to exit kiosk mode", e);
+                }
+            });
+        } catch (Exception e) {
+            call.reject("Failed to exit kiosk mode", e);
+        }
+    }
+
+    @PluginMethod
+    public void setAsLauncher(PluginCall call) {
+        try {
+            Context context = getContext();
+            if (context == null) {
+                call.reject("Context not available");
+                return;
+            }
+
+            // Enable launcher intent filter
+            ComponentName componentName = new ComponentName(context, getLauncherActivity());
+            PackageManager packageManager = context.getPackageManager();
+            packageManager.setComponentEnabledSetting(
+                componentName,
+                PackageManager.COMPONENT_ENABLED_STATE_ENABLED,
+                PackageManager.DONT_KILL_APP
+            );
+
+            // Open home screen settings
+            Intent intent = new Intent(android.provider.Settings.ACTION_HOME_SETTINGS);
+            intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+            context.startActivity(intent);
+
+            call.resolve();
+        } catch (Exception e) {
+            call.reject("Failed to set as launcher", e);
+        }
+    }
+
+    @PluginMethod
+    public void setAllowedKeys(PluginCall call) {
+        allowedKeys.clear();
+
+        // Parse allowed keys from options
+        if (call.getBoolean("volumeUp", false)) {
+            allowedKeys.add(KeyEvent.KEYCODE_VOLUME_UP);
+        }
+        if (call.getBoolean("volumeDown", false)) {
+            allowedKeys.add(KeyEvent.KEYCODE_VOLUME_DOWN);
+        }
+        if (call.getBoolean("back", false)) {
+            allowedKeys.add(KeyEvent.KEYCODE_BACK);
+        }
+        if (call.getBoolean("home", false)) {
+            allowedKeys.add(KeyEvent.KEYCODE_HOME);
+        }
+        if (call.getBoolean("recent", false)) {
+            allowedKeys.add(KeyEvent.KEYCODE_APP_SWITCH);
+        }
+        if (call.getBoolean("power", false)) {
+            allowedKeys.add(KeyEvent.KEYCODE_POWER);
+        }
+        if (call.getBoolean("camera", false)) {
+            allowedKeys.add(KeyEvent.KEYCODE_CAMERA);
+        }
+        if (call.getBoolean("menu", false)) {
+            allowedKeys.add(KeyEvent.KEYCODE_MENU);
+        }
+
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void getPluginVersion(PluginCall call) {
+        try {
+            JSObject ret = new JSObject();
+            ret.put("version", pluginVersion);
+            call.resolve(ret);
+        } catch (Exception e) {
+            call.reject("Could not get plugin version", e);
+        }
+    }
+
+    /**
+     * Handle key events to block hardware buttons when in kiosk mode
+     * This method should be called from the main activity's dispatchKeyEvent
+     */
+    @Override
+    protected void handleOnPause() {
+        super.handleOnPause();
+        if (isInKioskMode) {
+            Activity activity = getActivity();
+            if (activity != null) {
+                // Bring app back to foreground if in kiosk mode
+                ActivityManager activityManager = (ActivityManager) activity.getSystemService(Context.ACTIVITY_SERVICE);
+                if (activityManager != null) {
+                    activityManager.moveTaskToFront(activity.getTaskId(), 0);
+                }
+            }
+        }
+    }
+
+    /**
+     * Check if this app is set as the default launcher
+     */
+    private boolean checkIfLauncher() {
+        try {
+            Context context = getContext();
+            if (context == null) {
+                return false;
+            }
+
+            Intent intent = new Intent(Intent.ACTION_MAIN);
+            intent.addCategory(Intent.CATEGORY_HOME);
+
+            PackageManager packageManager = context.getPackageManager();
+            ComponentName componentName = intent.resolveActivity(packageManager);
+
+            if (componentName == null) {
+                return false;
+            }
+
+            return componentName.getPackageName().equals(context.getPackageName());
+        } catch (Exception e) {
+            return false;
+        }
+    }
+
+    /**
+     * Get the launcher activity class
+     * This should be the main activity of the Capacitor app
+     */
+    private Class<?> getLauncherActivity() {
+        Activity activity = getActivity();
+        if (activity != null) {
+            return activity.getClass();
+        }
+        return null;
+    }
+
+    /**
+     * Check if a key event should be blocked
+     * Call this from your MainActivity's dispatchKeyEvent method
+     */
+    public boolean shouldBlockKey(int keyCode) {
+        if (!isInKioskMode) {
+            return false;
+        }
+        return !allowedKeys.contains(keyCode);
+    }
+}