はじめに

パッケージをインストール
- npm
- pnpm
- yarn
- bun
Terminal window
npm i @capgo/capacitor-android-kiosk
Terminal window
pnpm add @capgo/capacitor-android-kiosk
Terminal window
yarn add @capgo/capacitor-android-kiosk
Terminal window
bun add @capgo/capacitor-android-kiosk
ネイティブプロジェクトと同期
- npm
- pnpm
- yarn
- bun
Terminal window
npx cap sync
Terminal window
pnpm cap sync
Terminal window
yarn cap sync
Terminal window
bunx cap sync

プラットフォームサポート

このプラグインはAndroid専用です。iOSのキオスクモード機能については、デバイスの組み込みガイドアクセス機能を使用してください。

機能

キオスクモード: システムUIを非表示にして没入型フルスクリーンモードに入る
ランチャー統合: アプリをデバイスのランチャー/ホームアプリとして設定
ハードウェアキー制御: 特定のハードウェアボタンをブロックまたは許可
ステータス検出: キオスクモードがアクティブかどうか、またはアプリがランチャーとして設定されているかを確認
Android 6.0以降: Android API 23からAndroid 15（API 35）までサポート

基本的な使用方法

キオスクモードへの入退出

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

// キオスクモードに入る
await CapacitorAndroidKiosk.enterKioskMode();

// キオスクモードを終了
await CapacitorAndroidKiosk.exitKioskMode();

// キオスクモードかどうかを確認
const { isInKioskMode } = await CapacitorAndroidKiosk.isInKioskMode();
console.log('Kiosk mode active:', isInKioskMode);

ランチャー機能

完全なキオスクモード機能のためには、アプリをデバイスのランチャーとして設定する必要があります:

// ユーザーがアプリをランチャーとして選択するためのホーム画面設定を開く
await CapacitorAndroidKiosk.setAsLauncher();

// アプリがランチャーとして設定されているか確認
const { isLauncher } = await CapacitorAndroidKiosk.isSetAsLauncher();
console.log('App is launcher:', isLauncher);

ハードウェアキー制御

キオスクモードで機能させるハードウェアボタンを制御:

// 音量キーのみ許可
await CapacitorAndroidKiosk.setAllowedKeys({
  volumeUp: true,
  volumeDown: true,
  back: false,
  home: false,
  recent: false
});

// すべてのキーをブロック（デフォルト）
await CapacitorAndroidKiosk.setAllowedKeys({});

完全な例

async function setupKioskMode() {
  try {
    // すでにランチャーとして設定されているか確認
    const { isLauncher } = await CapacitorAndroidKiosk.isSetAsLauncher();

    if (!isLauncher) {
      // ユーザーにランチャーとして設定するよう促す
      await CapacitorAndroidKiosk.setAsLauncher();
      alert('Please select this app as your Home app');
      return;
    }

    // 許可するキーを設定
    await CapacitorAndroidKiosk.setAllowedKeys({
      volumeUp: true,
      volumeDown: true,
      back: false,
      home: false,
      recent: false,
      power: false
    });

    // キオスクモードに入る
    await CapacitorAndroidKiosk.enterKioskMode();
    console.log('Kiosk mode activated');

  } catch (error) {
    console.error('Failed to setup kiosk mode:', error);
  }
}

APIリファレンス

isInKioskMode()

アプリが現在キオスクモードで実行されているかを確認します。

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

戻り値:

isInKioskMode (boolean): キオスクモードが現在アクティブかどうか

isSetAsLauncher()

アプリがデバイスのランチャー（ホームアプリ）として設定されているかを確認します。

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

戻り値:

isLauncher (boolean): アプリがデバイスのランチャーとして設定されているかどうか

enterKioskMode()

キオスクモードに入り、システムUIを非表示にしてハードウェアボタンをブロックします。これが効果的に機能するには、アプリをデバイスのランチャーとして設定する必要があります。

await CapacitorAndroidKiosk.enterKioskMode();

exitKioskMode()

キオスクモードを終了し、通常のシステムUIとハードウェアボタンの機能を復元します。

await CapacitorAndroidKiosk.exitKioskMode();

setAsLauncher()

このアプリをランチャーとして設定できるように、デバイスのホーム画面設定を開きます。完全なキオスクモード機能にはこれが必要です。

await CapacitorAndroidKiosk.setAsLauncher();

setAllowedKeys(options)

キオスクモードで機能させるハードウェアキーを設定します。デフォルトでは、キオスクモードですべてのハードウェアキーがブロックされます。

await CapacitorAndroidKiosk.setAllowedKeys({
  volumeUp: true,
  volumeDown: true,
  back: false,
  home: false,
  recent: false,
  power: false,
  camera: false,
  menu: false
});

パラメータ:

volumeUp (boolean, オプション): 音量アップボタンを許可（デフォルト: false）
volumeDown (boolean, オプション): 音量ダウンボタンを許可（デフォルト: false）
back (boolean, オプション): 戻るボタンを許可（デフォルト: false）
home (boolean, オプション): ホームボタンを許可（デフォルト: false）
recent (boolean, オプション): 最近使用したアプリボタンを許可（デフォルト: false）
power (boolean, オプション): 電源ボタンを許可（デフォルト: false）
camera (boolean, オプション): カメラボタンを許可（存在する場合）（デフォルト: false）
menu (boolean, オプション): メニューボタンを許可（存在する場合）（デフォルト: false）

getPluginVersion()

ネイティブCapacitorプラグインのバージョンを取得します。

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

戻り値:

version (string): プラグインのバージョン番号

Android設定

1. MainActivityのセットアップ

完全なハードウェアキーブロックを有効にするには、MainActivity.javaでdispatchKeyEventをオーバーライドする必要があります:

import android.view.KeyEvent;
import ee.forgr.plugin.android_kiosk.CapacitorAndroidKioskPlugin;

public class MainActivity extends BridgeActivity {
    @Override
    public boolean dispatchKeyEvent(KeyEvent event) {
        // キオスクプラグインを取得
        CapacitorAndroidKioskPlugin kioskPlugin = (CapacitorAndroidKioskPlugin)
            this.getBridge().getPlugin("CapacitorAndroidKiosk").getInstance();

        if (kioskPlugin != null && kioskPlugin.shouldBlockKey(event.getKeyCode())) {
            return true; // キーをブロック
        }

        return super.dispatchKeyEvent(event);
    }

    @Override
    public void onBackPressed() {
        // super.onBackPressed()を呼び出さずに戻るボタンを無効化
        // またはプラグインのhandleOnBackPressedを呼び出す
    }
}

2. AndroidManifest.xml

アプリをランチャーとして選択可能にするためにランチャーインテントフィルターを追加:

<activity
    android:name=".MainActivity"
    ...>

    <!-- 既存のインテントフィルター -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <!-- アプリをランチャーとして選択可能にするためにこれを追加 -->
    <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>

重要な注意事項

ランチャー要件: 完全なキオスクモード機能（ホームボタンのブロック、タスク切り替えの防止）には、アプリをデバイスのランチャーとして設定する必要があります。
テスト: テスト時は、プログラムでキオスクモードを終了するか、別のアプリをランチャーとして設定できます。
Androidバージョン: このプラグインは、Android 11以降の最新Android APIを使用し、Android 6.0以降との互換性のために古いメソッドにフォールバックします。
セキュリティ: このプラグインは正当なキオスクアプリケーション向けに設計されています。ユーザーがキオスクモードを終了する方法を提供してください。
バッテリー: キオスクモードは画面をオンのままにします。独自の画面タイムアウトまたは明るさ管理の実装を検討してください。

iOS代替案

iOSデバイスの場合は、組み込みのガイドアクセス機能を使用してください:

設定 > アクセシビリティ > ガイドアクセスに移動
ガイドアクセスをオンにする
パスコードを設定
アプリを開く
サイドボタンをトリプルクリック
設定を調整してガイドアクセスを開始

ベストプラクティス

最初にランチャーステータスを確認

const { isLauncher } = await CapacitorAndroidKiosk.isSetAsLauncher();
if (!isLauncher) {
  // 最初にランチャーとして設定するようユーザーに促す
  await CapacitorAndroidKiosk.setAsLauncher();
}

終了メカニズムを提供

// 特定のキーの組み合わせで終了を許可
// または秘密のジェスチャー/パターンを実装
async function exitKioskWithConfirmation() {
  const confirmed = confirm('Exit kiosk mode?');
  if (confirmed) {
    await CapacitorAndroidKiosk.exitKioskMode();
  }
}

アプリのライフサイクルを処理

// アプリが再開したときにキオスクモードに再入
window.addEventListener('resume', async () => {
  const { isInKioskMode } = await CapacitorAndroidKiosk.isInKioskMode();
  if (!isInKioskMode) {
    await CapacitorAndroidKiosk.enterKioskMode();
  }
});

エラー処理

try {
  await CapacitorAndroidKiosk.enterKioskMode();
} catch (error) {
  console.error('Failed to enter kiosk mode:', error);
  // ユーザーに通知して代替案を提供
}