> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/common/permission/album.md).

# 앨범

{% hint style="info" %}
**권한 설정이 필요해요**

`fetchAlbumItems`를 사용하기 전에 앨범 권한을 설정해야 해요. 권한 설정 가이드를 먼저 확인해 주세요.
{% endhint %}

***

### 1. 앨범 미디어 선택하기

**SDK 함수:** `fetchAlbumItems`

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

**시그니처**

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

**파라미터**

* **options** · `FetchAlbumItemsOptions`

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

**반환값**

* `Promise<AlbumItemResponse\[]>`

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

**에러**

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

**예제**

{% tabs %}
{% tab title="React" %}

```tsx
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);
  }
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
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);
  }
}
```

{% endtab %}
{% endtabs %}

**`FetchAlbumItemsOptions`**

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

프로퍼티:

* typesArray<'PHOTO' | 'VIDEO'>

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

  가져올 항목의 최대 개수예요.
* **maxWidthnumber** · `1024`

  이미지의 최대 폭이에요. 단위는 픽셀이에요.
* **base64boolean** · `false`

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

**`AlbumItemResponse`**

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

프로퍼티:

* idstring

  항목의 고유 ID예요.
* **data** · `Uristring`

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

  미디어 유형이에요.

***

### 2. 앨범 가져오기

**SDK 함수:** `fetchAlbumPhotos`

{% hint style="info" %}
**새 버전이 있어요**

`fetchAlbumPhotos`는 사진만 지원해요. 사진과 동영상을 함께 선택하거나 더 세밀한 제어가 필요하다면 [`fetchAlbumItems`](#_1-%EC%95%A8%EB%B2%94-%EB%AF%B8%EB%94%94%EC%96%B4-%EC%84%A0%ED%83%9D%ED%95%98%EA%B8%B0)를 사용해 주세요.
{% endhint %}

사용자 앨범에서 사진 목록을 불러오는 함수예요. 최대 개수와 해상도를 설정할 수 있어요.

**시그니처**

```typescript
function fetchAlbumPhotos(options: { maxCount: number; maxWidth: number; base64: boolean }): Promise<ImageResponse[]>;
```

**파라미터**

* **options** · 필수

  조회 옵션을 담은 객체예요.

  * **options.maxCount** · `number`

    가져올 사진의 최대 개수예요.
  * **options.maxWidth** · `number`

    사진의 최대 폭이에요. 단위는 픽셀이에요.
  * **options.base64** · `boolean`

    이미지를 Base64 형식으로 반환할지 설정해요.

**반환값**

* `Promise<ImageResponse\[]>`

  앨범 사진의 고유 ID와 데이터 URI를 포함한 배열을 반환해요.

**예제**

{% tabs %}
{% tab title="Web (JS)" %}

```js
import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError } from '@apps-in-toss/web-framework';

async function handleFetchAlbumPhotos() {
  try {
    const response = await fetchAlbumPhotos({ base64: true, maxWidth: 360 });
    response.forEach((image) => {
      const imageUri = 'data:image/jpeg;base64,' + image.dataUri;
      console.log('이미지 URI:', imageUri);
    });
  } catch (error) {
    if (error instanceof FetchAlbumPhotosPermissionError) {
      console.log('앨범 읽기 권한 없음');
    }
  }
}
```

{% endtab %}

{% tab title="Web (React)" %}

```tsx
import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError, ImageResponse } from '@apps-in-toss/web-framework';
import { useState } from 'react';

function AlbumPhotoList() {
  const [albumPhotos, setAlbumPhotos] = useState<ImageResponse[]>([]);

  const handlePress = async () => {
    try {
      const response = await fetchAlbumPhotos({ base64: true, maxWidth: 360 });
      setAlbumPhotos((prev) => [...prev, ...response]);
    } catch (error) {
      if (error instanceof FetchAlbumPhotosPermissionError) {
        // 앨범 읽기 권한 없음
      }
    }
  };

  return (
    <div>
      {albumPhotos.map((image) => {
        const imageUri = 'data:image/jpeg;base64,' + image.dataUri;
        return <img src={imageUri} key={image.id} />;
      })}
      <button onClick={handlePress}>앨범 가져오기</button>

  );
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError, ImageResponse } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Image, View } from 'react-native';

function AlbumPhotoList() {
  const [albumPhotos, setAlbumPhotos] = useState<ImageResponse[]>([]);

  const handlePress = async () => {
    try {
      const response = await fetchAlbumPhotos({ base64: true, maxWidth: 360 });
      setAlbumPhotos((prev) => [...prev, ...response]);
    } catch (error) {
      if (error instanceof FetchAlbumPhotosPermissionError) {
        // 앨범 읽기 권한 없음
      }
    }
  };

  return (
    <View>
      {albumPhotos.map((image) => {
        const imageUri = 'data:image/jpeg;base64,' + image.dataUri;
        return <Image source={{ uri: imageUri }} key={image.id} />;
      })}
      <Button title="앨범 가져오기" onPress={handlePress} />
      <Button
        title="권한 확인하기"
        onPress={async () => {
          const permission = await fetchAlbumPhotos.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="권한 요청하기"
        onPress={async () => {
          const permission = await fetchAlbumPhotos.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </View>
  );
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/common/permission/album.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.