openPermissionDialog

OS 표준 권한 요청 다이얼로그를 표시합니다. 권한 상태가 notDetermined일 때 사용자의 최초 동의를 받기 위해 사용합니다. 다이얼로그 선택 결과('allowed' 또는 'denied')를 resolve 합니다.

시그니처

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

declare function openPermissionDialog(permission: {
  name: PermissionName;
  access: PermissionAccess;
}): Promise<'allowed' | 'denied'>;

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

파라미터

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

반환값

• Promise<'allowed' | 'denied'> — 사용자가 다이얼로그에서 선택한 결과:
  • 'allowed' — 사용자가 허용을 선택했습니다.
  • 'denied' — 사용자가 거절을 선택했습니다.

denied 상태에서 재호출

권한이 이미 denied 상태일 때 openPermissionDialog를 호출하면 iOS에서는 다이얼로그가 표시되지 않고 즉시 'denied'로 resolve 되는 경우가 많습니다. denied 상태의 회복은 OS 설정 화면에서만 가능하며, 앱에서 할 수 있는 것은 "설정 → 토스 → 권한" 경로를 안내하는 것뿐입니다. 호출 전에 getPermission으로 상태를 먼저 확인하는 것이 안전합니다.

권한

openPermissionDialog 자체는 별도의 권한이 필요하지 않습니다 — 권한을 요청하는 함수입니다. 표준 처리 흐름은 Guides — 권한 처리 패턴을 참고하세요.

예제

최소 예제

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

const result = await openPermissionDialog({ name: 'camera', access: 'read' });
console.log('User chose:', result); // 'allowed' | 'denied'

실전 예제 — 상태 확인 후 조건부 다이얼로그 표시

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

async function requestCameraIfNeeded(): Promise<boolean> {
  const status = await getPermission({ name: 'camera', access: 'read' });

  // 이미 결정된 상태라면 다이얼로그를 띄우지 않는다.
  if (status === 'allowed') return true;
  if (status === 'denied') {
    // denied는 OS 설정에서만 회복된다 — 안내 메시지만 표시.
    showAppToast('카메라 권한이 거절되었습니다. 설정에서 허용해 주세요.');
    return false;
  }

  // notDetermined일 때만 다이얼로그를 표시한다.
  const result = await openPermissionDialog({ name: 'camera', access: 'read' });
  if (result === 'denied') {
    showAppToast('카메라 권한을 허용해야 사진을 찍을 수 있어요.');
    return false;
  }
  return true;
}

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

실전 예제 — React 버튼 클릭 시 권한 요청

import { openPermissionDialog } from '@apps-in-toss/web-framework';
import { useState } from 'react';

function RequestLocationButton() {
  const [result, setResult] = useState<'allowed' | 'denied' | null>(null);

  const handleRequest = async () => {
    try {
      const status = await openPermissionDialog({ name: 'geolocation', access: 'read' });
      setResult(status);
    } catch (error) {
      console.error('권한 다이얼로그 오류:', error);
    }
  };

  return (
    <div>
      <button type="button" onClick={handleRequest}>위치 권한 요청</button>
      {result && <p>결과: {result}</p>}
    </div>
  );
}

직접 실행해 보기

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

→sdk-example에서 실행해 보기

관련 API

• getPermission — 현재 권한 상태를 확인합니다. 다이얼로그 표시 전에 먼저 호출하는 것이 안전합니다.
• requestPermission — 상태 확인과 다이얼로그를 하나로 합친 편의 함수입니다.

관련 가이드

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

외부 참조

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