시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그런 다음 아래 프롬프트를 사용하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

npm install @capgo/capacitor-android-kiosk
npx cap sync

가져오기

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

빠른 시작

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

await CapacitorAndroidKiosk.enterKioskMode();

자주 하는 실수

• 런처: 안정적인 키오스크 잠금을 위해 앱을 기본 런처로 설정하세요.
• MDM: fleet 빌드를 배포하기 전에 escape hatch를 검증하세요.
• iOS: 지원되지 않습니다.

API 개요

isInKioskMode

앱이 현재 키오스크 모드로 실행 중인지 확인합니다.

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

const { isInKioskMode } = await CapacitorAndroidKiosk.isInKioskMode();
console.log('Kiosk mode active:', isInKioskMode);

isSetAsLauncher

앱이 기기 런처(홈 앱)로 설정되어 있는지 확인합니다.

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

const { isLauncher } = await CapacitorAndroidKiosk.isSetAsLauncher();
console.log('Is launcher:', isLauncher);

enterKioskMode

키오스드 모드로 진입하여 시스템 UI를 숨기고 하드웨어 버튼을 차단합니다. 또한 앱이 시스템에 의해 종료되는 것을 방지하기 위해 포그라운드 keep-alive 서비스를 시작합니다. 이 기능이 효과적으로 작동하려면 앱을 기기의 런처로 설정해야 합니다.

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

await CapacitorAndroidKiosk.enterKioskMode();

exitKioskMode

키오스드 모드를 종료하여 정상적인 시스템 UI와 하드웨어 버튼 기능을 복원합니다. 또한 enterKioskMode()에서 시작된 포그라운드 keep-alive 서비스를 중지합니다.

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

await CapacitorAndroidKiosk.exitKioskMode();
console.log('Exited kiosk mode');

setAsLauncher

사용자가 이 앱을 런처로 설정할 수 있도록 기기의 홈 화면 설정을 엽니다. 완전한 키오스드 모드 기능을 위해 필요합니다.

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

await CapacitorAndroidKiosk.setAsLauncher();
// User will be prompted to select this app as the home app

setAllowedKeys

키오스드 모드에서 기능이 허용되는 하드웨어 키를 설정합니다. 기본적으로 키오스드 모드에서는 모든 하드웨어 키가 차단됩니다.

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

// Allow volume keys only
await CapacitorAndroidKiosk.setAllowedKeys({
  volumeUp: true,
  volumeDown: true,
  back: false,
  home: false,
  recent: false
});

타입 레퍼런스

EnterKioskModeOptions

선택적 플래그: enterKioskMode.

export interface EnterKioskModeOptions {
  /**
   * After reboot, start the app so you can call `enterKioskMode()` again. Best-effort only (OEM
   * behavior, force-stop). Omit to keep the saved value. Cleared when you call `exitKioskMode()`.
   */
  restoreAfterReboot?: boolean;

  /**
   * Periodically tries to bring the app to the foreground. Skipped while the screen is off. Often
   * blocked from the background on some devices—being the default launcher, relaxing battery limits,
   * and allowing exact alarms (where required) improve odds. Omit to keep the saved value.
   */
  relaunch?: boolean;

  /** Minutes between relaunch attempts when `relaunch` is on. Range 5–60; default 15. */
  relaunchIntervalMinutes?: number;
}

AllowedKeysOptions

키오스크 모드에서 허용할 하드웨어 키 설정 옵션입니다.

export interface AllowedKeysOptions {
  /**
   * Allow volume up button
   * @default false
   */
  volumeUp?: boolean;

  /**
   * Allow volume down button
   * @default false
   */
  volumeDown?: boolean;

  /**
   * Allow back button
   * @default false
   */
  back?: boolean;

  /**
   * Allow home button
   * @default false
   */
  home?: boolean;

  /**
   * Allow recent apps button
   * @default false
   */
  recent?: boolean;

  /**
   * Allow power button
   * @default false
   */
  power?: boolean;

  /**
   * Allow camera button (if present)
   * @default false
   */
  camera?: boolean;

  /**
   * Allow menu button (if present)
   * @default false
   */
  menu?: boolean;
}

Source of Truth

이 페이지는 플러그인의 src/definitions.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.

시작하기 다음 단계

사용 중이라면 시작하기 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 @capgo/capacitor-android-kiosk 사용하기 @capgo/capacitor-android-kiosk 사용 시 네이티브 기능을 위해, API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 API Keys의 구현 세부 사항은, 기기 Devices의 구현 세부 사항은.