openCamera

카메라를 실행해 사용자가 촬영한 이미지를 반환합니다. 프로필 사진 촬영, 영수증 스캔, 인증 사진 제출 등 카메라를 이용한 단발성 이미지 수집에 적합합니다.

시그니처

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

declare function openCamera(options?: OpenCameraOptions): Promise<ImageResponse>;

interface OpenCameraOptions {
  /** 이미지를 Base64 형식으로 반환할지 여부. 기본값: `false`. */
  base64?: boolean;
  /** 이미지의 최대 너비(픽셀). 기본값: `1024`. */
  maxWidth?: number;
}

interface ImageResponse {
  /** 가져온 사진의 고유 ID. */
  id: string;
  /**
   * 사진의 데이터 URI.
   * `base64: true`인 경우 Base64 인코딩된 문자열로 반환됩니다.
   */
  dataUri: string;
}

파라미터

이름	타입	필수	설명
options	OpenCameraOptions	—	생략 가능. 아래 옵션 필드 참고.
options.base64	boolean	—	true로 설정하면 dataUri에 Base64 인코딩된 문자열을 반환합니다. 기본값 false.
options.maxWidth	number	—	반환 이미지의 최대 너비(픽셀). 기본값 1024.

반환값

• Promise<ImageResponse> — 촬영된 이미지의 고유 ID와 데이터 URI를 담은 객체로 resolve됩니다.
• 권한 denied로 인한 실패는 "권한" 섹션 참고. 카메라 접근 실패나 사용자 촬영 취소 시에도 reject될 수 있으므로 try/catch를 반드시 사용하세요.

base64: true일 때 데이터 URI prefix 처리

base64: true 옵션을 사용하면 dataUri에는 JPEG Base64 문자열만 담깁니다. <img src> 등에 사용하려면 'data:image/jpeg;base64,' + response.dataUri처럼 데이터 URL 스키마 prefix를 직접 붙여야 합니다.

권한

Camera 권한이 필요합니다. 권한이 명시적으로 denied 상태이면 호출이 실패하므로 try/catch로 감싸세요. notDetermined 상태에서는 호출이 그대로 진행될 수 있지만, 사용자 경험상 먼저 다이얼로그로 승격시키는 것이 안전합니다. 상세 처리 패턴은 Guides — 권한 처리 패턴을 참고하세요.

호출부에 붙어 있는 유틸:

const status = await openCamera.getPermission();
// 'allowed' | 'denied' | 'notDetermined'

if (status !== 'allowed') {
  await openCamera.openPermissionDialog();
}

예제

최소 예제

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

async function takePhoto() {
  const response = await openCamera();
  console.log('이미지 ID:', response.id);
  console.log('데이터 URI:', response.dataUri);
}

실전 예제 — 프로필 사진 촬영 후 미리보기

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

export function ProfilePhotoCapture() {
  const [previewSrc, setPreviewSrc] = useState<string | null>(null);
  const [message, setMessage] = useState('');
  const [pending, setPending] = useState(false);

  async function handleCapture() {
    setPending(true);
    setMessage('');
    try {
      const status = await openCamera.getPermission();
      if (status === 'denied') {
        setMessage('설정에서 카메라 권한을 허용해 주세요.');
        return;
      }
      if (status === 'notDetermined') {
        await openCamera.openPermissionDialog();
      }

      // base64: true로 받아 <img>에 바로 표시합니다.
      const response = await openCamera({ base64: true, maxWidth: 512 });
      // Base64 문자열에는 데이터 URL prefix가 없으므로 직접 붙입니다.
      setPreviewSrc('data:image/jpeg;base64,' + response.dataUri);
    } catch (error) {
      // 권한이 위 체크와 호출 사이에 회수됐거나 사용자가 촬영을 취소한 경우.
      setMessage('사진을 가져오지 못했어요. 다시 시도해 주세요.');
      console.error(error);
    } finally {
      setPending(false);
    }
  }

  return (
    <div>
      <button type="button" onClick={handleCapture} disabled={pending}>
        {pending ? '카메라 실행 중...' : '프로필 사진 촬영'}
      </button>
      {previewSrc && (
        <img src={previewSrc} alt="촬영된 프로필 사진 미리보기" width={200} height={200} />
      )}
      {message && <p role="status">{message}</p>}
    </div>
  );
}

직접 실행해 보기

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

→sdk-example에서 실행해 보기

관련 API

• fetchAlbumPhotos — 카메라 촬영 없이 앨범에서 이미지를 가져옵니다.

관련 가이드

• Guides — 권한 처리 패턴 — getPermission / openPermissionDialog 공통 흐름.
• Guides — 카메라·앨범 UX 패턴

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.
• 표준 Web API 대응: MediaDevices.getUserMedia — 브라우저에서의 카메라 접근 표준 API.