getPermission

특정 권한의 현재 상태(allowed / denied / notDetermined)를 반환합니다. 권한이 필요한 API를 호출하기 전에 상태를 점검해 불필요한 실패를 예방하는 데 사용합니다.

시그니처

import { getPermission } from '@apps-in-toss/web-framework';

declare function getPermission(permission: {
  name: PermissionName;
  access: PermissionAccess;
}): Promise<PermissionStatus>;

type PermissionName = 'camera' | 'photos' | 'contacts' | 'geolocation' | 'microphone' | 'clipboard';
type PermissionAccess = 'read' | 'write' | 'access';
type PermissionStatus = 'notDetermined' | 'denied' | 'allowed';

파라미터

이름	타입	필수	설명
permission.name	PermissionName	✓	확인할 권한의 이름. 'camera' / 'photos' / 'contacts' / 'geolocation' / 'microphone' / 'clipboard' 중 하나.
permission.access	PermissionAccess	✓	접근 유형. 'read' / 'write' / 'access' 중 하나.

반환값

• Promise<PermissionStatus> — 현재 권한 상태:
  • 'allowed' — 사용자가 권한을 허용한 상태.
  • 'denied' — 사용자가 거절했거나 OS가 차단한 상태. 이 상태에서 해당 API를 호출하면 throw합니다.
  • 'notDetermined' — 아직 사용자가 결정하지 않은 상태. 최초 진입 시 기본값.

권한

getPermission 자체는 별도의 권한이 필요하지 않습니다 — 권한 상태를 조회하는 함수입니다. 권한이 필요한 다른 API의 처리 흐름은 Guides — 권한 처리 패턴을 참고하세요.

예제

최소 예제

import { getPermission } from '@apps-in-toss/web-framework';

const status = await getPermission({ name: 'camera', access: 'read' });
console.log('Camera permission:', status);
// 'allowed' | 'denied' | 'notDetermined'

실전 예제 — check → prompt → invoke 흐름

import { getPermission, openPermissionDialog, openCamera } from '@apps-in-toss/web-framework';

async function takePicture() {
  // 1. 현재 상태를 먼저 확인한다.
  const status = await getPermission({ name: 'camera', access: 'read' });

  if (status === 'denied') {
    // 2. denied 상태에서는 다이얼로그를 다시 띄워도 의미 없다.
    //    사용자에게 OS 설정 화면 안내만 표시한다.
    showAppToast('카메라 권한이 거절되었습니다. 설정에서 허용해 주세요.');
    return;
  }

  if (status === 'notDetermined') {
    // 3. 아직 결정하지 않은 상태라면 다이얼로그를 띄워 동의를 받는다.
    const result = await openPermissionDialog({ name: 'camera', access: 'read' });
    if (result === 'denied') {
      showAppToast('카메라 권한을 허용해야 사진을 찍을 수 있어요.');
      return;
    }
  }

  // 4. allowed가 보장된 시점에 실제 API를 호출한다.
  const photo = await openCamera({ type: 'photo' });
  console.log('Photo captured:', photo);
}

// `showAppToast`는 SDK가 제공하지 않습니다 — 앱의 자체 토스트/스낵바 컴포넌트로 대체하세요.
declare function showAppToast(message: string): void;

실전 예제 — React에서 컴포넌트 마운트 시 상태 표시

import { getPermission, type PermissionStatus } from '@apps-in-toss/web-framework';
import { useEffect, useState } from 'react';

function CameraPermissionBadge() {
  const [status, setStatus] = useState<PermissionStatus | null>(null);

  useEffect(() => {
    getPermission({ name: 'camera', access: 'read' })
      .then(setStatus)
      .catch(console.error);
  }, []);

  if (status === null) return <span>확인 중...</span>;
  if (status === 'allowed') return <span>카메라 권한 허용됨</span>;
  if (status === 'denied') return <span>카메라 권한 거절됨</span>;
  return <span>카메라 권한 미결정</span>;
}

직접 실행해 보기

sdk-example의 Permissions 페이지에서 getPermission 카드를 실행해 결과를 확인할 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• openPermissionDialog — 권한 요청 시스템 다이얼로그를 표시합니다.
• requestPermission — 상태 확인과 다이얼로그를 하나로 합친 편의 함수입니다.

관련 가이드

• Guides — 권한 처리 패턴 — check → prompt → invoke 표준 흐름, 거절 처리, 환경별 차이.

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.