react-native-kiosk-manager

A React Native library for managing kiosk mode on Android devices.

中文文档 | English

⚠️ Android only: This package is designed for Android devices and will not work on iOS.

Installation

npm install react-native-kiosk-manager

Android Permission Configuration

Automatic Merging

After installing this library, the following will be automatically merged into your application without manual configuration:

• ✅ All permission declarations
• ✅ BootReceiver component
• ✅ DeviceAdminReceiver component
• ✅ FileProvider component

You do NOT need to manually declare these components in AndroidManifest.xml!

Files You Need to Manually Create

Although components are automatically merged, you need to manually create the following XML resource files:

1. Required: android/app/src/main/res/xml/device_admin_receiver.xml

<?xml version="1.0" encoding="utf-8"?>
<device-admin xmlns:android="http://schemas.android.com/apk/res/android">
  <uses-policies>
    <force-lock />
    <lock-task />
  </uses-policies>
</device-admin>

2. Optional (only if you rely on the built-in APK install features): create android/app/src/main/res/xml/file_provider_paths.xml. If your app provides its own FileProvider or you don’t use the downloader/installer APIs, you can skip this file.

<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
    <external-files-path name="apk_updates" path="." />
    <external-path name="external" path="." />
</paths>

Detailed Setup Guide

📖 Complete Setup Documentation: AndroidManifest.xml Setup Guide

Usage

import KioskManager from 'react-native-kiosk-manager';

// Start kiosk mode
KioskManager.startKiosk();

// Stop kiosk mode
KioskManager.stopKiosk();

// Check if device owner
const isOwner = await KioskManager.isDeviceOwner();

// Clear device owner
await KioskManager.clearDeviceOwner();

APK Installation & Auto-Launch Notes

When using silentInstallApk, silentInstallAndLaunchApk, or downloadAndSilentInstallAndLaunchApk, keep the following in mind:

• Device Owner required – Silent install and background launch only work when the calling app is the device owner. Confirm with await KioskManager.isDeviceOwner() before invoking the APIs.
• Launcher activity needed – The target APK must expose an activity with action.MAIN + category.LAUNCHER; otherwise neither the standard intent nor am start fallback can bring it to the foreground.
• Same-version updates – If you reinstall an APK without bumping versionCode, it must still be re-built/signed so that Android updates the package lastUpdateTime. The library now detects either a higher version code or a newer lastUpdateTime to decide when installation has completed and will auto-start even for same-version hotfixes.
• Custom manifest merges – The install-complete broadcast action is derived from your final applicationId (${applicationId}.INSTALL_COMPLETE). Avoid hard-coding another action name in your manifest, or the auto-start broadcast will be missed.
• Android 13+ broadcast flag – Starting with API 33, dynamic receivers must declare whether they are exported. The library registers its install-complete receiver with Context.RECEIVER_NOT_EXPORTED; if you override this behaviour, be sure to keep the same flag to prevent runtime registration errors.
• Debugging tip – To verify install broadcasts and launch attempts, capture logs with adb logcat -v time -s InstallCompleteReceiver KioskManager immediately after triggering a silent install.

DeviceAdminReceiver 配置说明 / DeviceAdminReceiver Setup

注意 / Note:
集成本库的 App 需要在自己的包名下创建 DeviceAdminReceiver.kt，并参考 example 目录下的实现：
Apps integrating this library must create their own DeviceAdminReceiver.kt under their package, following the example implementation.

1. 在你的项目中创建如下文件（以包名为例：com.yourcompany.yourapp）：
   Create the following file in your project (replace with your actual package name):

   android/app/src/main/java/com/yourcompany/yourapp/DeviceAdminReceiver.kt

2. 内容可参考 example：
   The content can refer to the example:

   package com.yourcompany.yourapp
   import android.app.admin.DeviceAdminReceiver
   
   class DeviceAdminReceiver : DeviceAdminReceiver() {}

3. AndroidManifest.xml 中的 <receiver> 也要使用你自己的包名和类名。
   The <receiver> in AndroidManifest.xml should also use your own package and class name.

参考实现 / Reference:
可直接参考 example/android/app/src/main/java/com/kioskmanager/example/DeviceAdminReceiver.kt.

Device Owner Setup Guide

Quick Setup (Recommended)

Use our automated setup scripts:

# Linux/macOS
npm run setup-device-owner

# Windows
npm run setup-device-owner-windows

These scripts will guide you through the entire process automatically!

Method 1: Using ADB (Android Debug Bridge)

Prerequisites

• Device must be factory reset or never had a user account added
• USB debugging must be enabled
• ADB must be installed on your computer

Steps

1. Factory reset the device (if not already done)

   # Optional: Reset via ADB
   adb shell am broadcast -a android.intent.action.MASTER_CLEAR

2. Skip the setup wizard without adding any accounts

   • Do not sign in to Google account
   • Do not add any user accounts

3. Enable Developer Options

   • Go to Settings > About phone
   • Tap "Build number" 7 times
   • Go back to Settings > Developer options
   • Enable "USB debugging"

4. Connect device to computer and verify ADB connection

   adb devices

5. Set your app as Device Owner

   # Replace com.yourcompany.yourapp with your actual package name
   adb shell dpm set-device-owner com.yourcompany.yourapp/.DeviceAdminReceiver

6. Verify Device Owner status

   adb shell dpm list-owners

Example Commands for This Library

# For the example app
adb shell dpm set-device-owner com.kioskmanager.example/.DeviceAdminReceiver

# For your production app (replace with your package name)
adb shell dpm set-device-owner com.yourcompany.yourapp/.DeviceAdminReceiver

Method 2: Using MDM (Mobile Device Management)

Enterprise Solutions

• Google Workspace Admin Console
• Microsoft Intune
• VMware Workspace ONE
• Samsung Knox
• Custom EMM solutions

General MDM Setup Process

1. Enroll device in MDM

   • Factory reset the device
   • During setup, scan QR code or enter enrollment details
   • Device will be provisioned as managed device

2. Configure Device Owner via MDM

   • Set your app as the device owner through MDM console
   • Deploy the app via MDM
   • Configure kiosk policies

3. Benefits of MDM approach

   • Remote management
   • Bulk deployment
   • Policy enforcement
   • Remote wipe capabilities

Method 3: Using Android Enterprise (Zero-Touch)

For Large Scale Deployments

1. Register with Android Enterprise

   • Sign up for Android Enterprise
   • Configure zero-touch enrollment

2. Device Configuration

   • Devices are automatically enrolled when first powered on
   • Your app is automatically set as device owner
   • No manual setup required

Important Notes

⚠️ Critical Requirements:

• Device must be in factory reset state
• No user accounts can be added before setting device owner
• Once device owner is set, it cannot be changed without factory reset
• Device owner has extensive system privileges

⚠️ Security Considerations:

• Device owner has full device control
• Can install/uninstall apps silently
• Can modify system settings
• Can wipe device remotely

Troubleshooting

Common Issues

1. "Not allowed to set the device owner"

   • Solution: Factory reset and try again without adding accounts

2. "Device owner is already set"

   • Solution: Clear existing device owner first

   adb shell dpm remove-active-admin com.existing.package/.AdminReceiver

3. "User is not empty"

   • Solution: Remove all user accounts and try again

4. ADB not recognized

   • Solution: Install Android SDK Platform Tools
   • Add ADB to system PATH

Verification Commands

# Check current device owner
adb shell dpm list-owners

# Check if device is provisioned
adb shell getprop ro.setupwizard.mode

# List all device admin receivers
adb shell pm list packages -a | grep admin

Development vs Production

Development

• Use ADB method for testing
• Easy to reset and reconfigure
• Good for debugging

Production

• Use MDM or Zero-Touch enrollment
• Scalable for multiple devices
• Professional device management

For Production Deployment

📖 Complete Production Guide - Detailed production environment deployment and management guide

API Reference

Methods

startKiosk()

Starts kiosk mode on the device.

KioskManager.startKiosk();

stopKiosk()

Stops kiosk mode and returns to normal operation.

KioskManager.stopKiosk();

isDeviceOwner(): Promise<boolean>

Checks if the current app is set as device owner.

const isOwner = await KioskManager.isDeviceOwner();
console.log('Is Device Owner:', isOwner);

clearDeviceOwner(): Promise<void>

Clears the device owner status (requires device owner privileges).

await KioskManager.clearDeviceOwner();

Requirements

• React Native >= 0.60
• Android API Level 21+ (Android 5.0+)
• Device Owner privileges for full functionality

Limitations

• Android only (iOS not supported)
• Requires Device Owner setup
• Some features may not work on all Android versions/OEMs
• Factory reset required to change Device Owner

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library