앨범 미디어 선택하기 (fetchAlbumItems)

지원환경: React NativeReact Native SDKv2.6.0WebViewWebView SDKv2.6.0

실행환경: Toss AppSandbox App

fetchAlbumItems는 사용자 앨범에서 사진·동영상을 선택해 가져오는 함수예요.
사진과 동영상을 동시에 선택할 수 있으며, 사용자가 선택을 취소하면 빈 배열 []을 반환해요.

시그니처

function fetchAlbumItems(options?: FetchAlbumItemsOptions): Promise<AlbumItemResponse[]>;

파라미터

• optionsFetchAlbumItemsOptions
  

  조회 옵션을 담은 객체예요. 자세한 타입은 FetchAlbumItemsOptions를 참고하세요.

반환값

• Promise<AlbumItemResponse[]>
  

  선택한 미디어 목록을 반환해요. 사용자가 취소하면 빈 배열을 반환해요.

에러

에러 코드	발생 조건
NOT_ALLOWED	앨범 접근이 허용되지 않았을 때
INVALID_REQUEST	요청 파라미터가 올바르지 않을 때
INVALID_DATA	미디어 데이터가 유효하지 않을 때
UNSUPPORTED_APP_VERSION	토스앱 버전이 5.261.0보다 낮을 때

예제

React

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

async function pickMedia() {
  try {
    const items = await fetchAlbumItems({
      types: ['PHOTO', 'VIDEO'],
      maxCount: 5,
      base64: true,
    });

    if (items.length === 0) {
      console.log('선택이 취소되었어요.');
      return;
    }

    items.forEach((item) => {
      console.log(item.type, item.id);
    });
  } catch (error) {
    console.error('앨범 조회 오류:', error.code);
  }
}

React Native

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

async function pickMedia() {
  try {
    const items = await fetchAlbumItems({
      types: ['PHOTO', 'VIDEO'],
      maxCount: 5,
      base64: true,
    });

    if (items.length === 0) {
      console.log('선택이 취소되었어요.');
      return;
    }

    items.forEach((item) => {
      console.log(item.type, item.id);
    });
  } catch (error) {
    console.error('앨범 조회 오류:', error.code);
  }
}

FetchAlbumItemsOptions

fetchAlbumItems 함수에 전달하는 옵션 타입이에요.

시그니처

interface FetchAlbumItemsOptions {
  types?: AlbumItemType[];
  maxCount?: number;
  maxWidth?: number;
  base64?: boolean;
}

프로퍼티

• typesArray<'PHOTO' | 'VIDEO'>
  

  가져올 미디어 유형 목록이에요. 'PHOTO'(사진), 'VIDEO'(동영상) 중 선택할 수 있어요. 지정하지 않으면 사진만 가져와요.

• maxCountnumber · 10
  

  가져올 항목의 최대 개수예요.

• maxWidthnumber · 1024
  

  이미지의 최대 폭이에요. 단위는 픽셀이에요.

• base64boolean · false
  

  이미지의 dataUri를 Base64 문자열로 반환할지 여부예요.

AlbumItemResponse

fetchAlbumItems가 반환하는 미디어 항목 타입이에요.

시그니처

interface AlbumItemResponse {
  id: string;
  dataUri: string;
  type: AlbumItemType;
}

프로퍼티

• idstring
  

  항목의 고유 ID예요.

• dataUristring
  

  미디어 데이터 URI예요. type이 PHOTO이면서 base64 옵션이 true이면 Base64 문자열로 반환돼요.

• type'PHOTO' | 'VIDEO'
  

  미디어 유형이에요.