> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Economy v2의 고정 콘텐츠 컨테이너

> 가상 화폐 토큰과 구매 시 고정 보상을 열어주는 번들을 결합하여 Economy v2에서 레거시 PlayFab 컨테이너 아이템을 재현합니다.

<Info>
  Economy v2는 이제 정식 출시(GA)되었습니다. 지원 및 피드백은 [PlayFab 포럼](https://community.playfab.com)을 참조하세요.
</Info>

Economy v1(레거시)에는 기본 제공 **컨테이너** 기능이 있었습니다. 즉, 열면 그 콘텐츠를 플레이어의 인벤토리에 부여하는 특수 카탈로그 아이템이었습니다. Economy v2에는 컨테이너가 기본 아이템 유형으로 포함되어 있지 않지만, 가상 화폐와 번들의 조합을 사용해 **고정 콘텐츠 컨테이너**(항상 동일한 아이템을 부여하는 컨테이너)에 대해 동일한 동작을 구현할 수 있습니다.

## 작동 방식

이 패턴은 세 가지 Economy v2 빌딩 블록을 사용합니다.

1. 컨테이너 자체를 나타내는 **가상 화폐(또는 스택 가능한 아이템)**, 예를 들어 "Treasure Chest Token".
2. 해당 화폐 1개로 가격이 매겨진 **번들**로, 컨테이너가 부여해야 할 아이템을 포함합니다.
3. 플레이어가 토큰 1개를 사용하여 번들을 구매하는 **구매 호출**로, 아이템을 자동으로 열어 부여합니다.

플레이어의 관점에서는 (게임 플레이 보상, 스토어 구매 등을 통해) 토큰을 받은 다음 이를 "열어" 그 안의 아이템을 얻습니다. 이는 v1 컨테이너가 작동하는 방식과 정확히 동일합니다.

## 필수 구성 요소

* [PlayFab 개발자 계정](https://developer.playfab.com/en-us/sign-up).
* [Game Manager](https://developer.playfab.com/)에서 만든 타이틀.
* 컨테이너가 부여할 게시된 카탈로그 아이템이 하나 이상.

## 1단계: 컨테이너용 가상 화폐 만들기

컨테이너를 나타내는 가상 화폐를 만듭니다. 이 화폐의 각 단위는 열지 않은 컨테이너 하나 역할을 합니다.

### Game Manager

1. **Economy** > **Catalog (V2)** > **Currency**로 이동합니다.
2. **New currency**를 선택합니다.
3. **Title**을 `Treasure Chest`와 같은 설명적인 이름으로 설정합니다.
4. **FriendlyId**를 `tc`와 같은 짧은 코드로 설정합니다.
5. **Save and publish**를 선택합니다.

### REST API

[CreateDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/create-draft-item)을 호출합니다.

```json theme={null}
{
  "Item": {
    "CreatorEntity": {
      "Id": "{{TitleID}}",
      "Type": "title"
    },
    "Type": "currency",
    "AlternateIds": [
      {
        "Type": "FriendlyId",
        "Value": "tc"
      }
    ],
    "Title": {
      "NEUTRAL": "Treasure Chest"
    },
    "Description": {
      "NEUTRAL": "A treasure chest that can be opened to reveal its contents."
    },
    "StartDate": "2023-07-27T00:00:00.000Z"
  },
  "Publish": true
}
```

***

## 2단계: 컨테이너 토큰 1개로 가격이 매겨진 번들 만들기

컨테이너가 부여할 아이템을 담고 있는 번들을 만듭니다. 번들의 가격을 컨테이너 화폐 정확히 1단위로 설정합니다.

### Game Manager

1. **Economy** > **Catalog (V2)** > **Bundles**로 이동합니다.
2. **New bundle**을 선택합니다.
3. **Title**을 `Treasure Chest Contents`와 같이 컨테이너의 콘텐츠를 설명하는 이름으로 설정합니다.
4. **Items**에서 컨테이너가 부여할 아이템과 수량을 추가합니다. 예를 들어, **Legendary Sword** 1개와 **Gold** 100개.
5. **Price**에서 가격을 컨테이너 화폐(**Treasure Chest**)의 **1**로 설정합니다.
6. **Save and publish**를 선택합니다.

### REST API

[CreateDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/create-draft-item)을 호출합니다.

```json theme={null}
{
  "Item": {
    "Type": "bundle",
    "Title": {
      "NEUTRAL": "Treasure Chest Contents"
    },
    "StartDate": "2023-07-27T00:00:00.000Z",
    "ItemReferences": [
      {
        "Id": "{{LegendarySwordID}}",
        "Amount": 1
      },
      {
        "Id": "{{GoldCurrencyID}}",
        "Amount": 100
      }
    ],
    "PriceOptions": {
      "Prices": [
        {
          "Amounts": [
            {
              "ItemId": "{{TreasureChestCurrencyID}}",
              "Amount": 1
            }
          ]
        }
      ]
    }
  },
  "Publish": true
}
```

***

플레이어가 이 번들을 구매하면 번들이 [자동으로 열려서](/services/playfab/economy-monetization/economy-v2/catalog/bundles#purchasing-and-unpacking-bundles) 개별 아이템이 플레이어의 인벤토리로 바로 이동합니다.

## 3단계: 플레이어에게 컨테이너 토큰 부여

게임 디자인에 맞는 어떤 메커니즘을 통해서든 플레이어에게 컨테이너 화폐를 부여합니다.

* **게임플레이 보상** — [AddInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/add-inventory-items)를 사용해 레벨, 퀘스트 또는 업적을 완료한 후 토큰을 부여합니다.
* **스토어 구매** — 컨테이너 토큰을 다른 가상 화폐 또는 실제 통화로 [스토어](/services/playfab/economy-monetization/economy-v2/catalog/stores)에서 판매합니다.
* **배틀 패스 / 시즌 보상** — 토큰을 보상 등급으로 포함시킵니다.

`AddInventoryItems`를 사용해 Treasure Chest 토큰 3개를 부여하는 예시:

```json theme={null}
{
  "Entity": {
    "Type": "title_player_account",
    "Id": "{{PlayerID}}"
  },
  "Item": {
    "Id": "{{TreasureChestCurrencyID}}"
  },
  "Amount": 3
}
```

## 4단계: 컨테이너 열기

플레이어가 컨테이너를 열고자 할 때, [PurchaseInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/purchase-inventory-items)를 호출해 컨테이너 토큰 1개로 번들을 구매합니다.

```json theme={null}
{
  "Entity": {
    "Type": "title_player_account",
    "Id": "{{PlayerID}}"
  },
  "Item": {
    "Id": "{{TreasureChestContentsBundleID}}"
  },
  "Amount": 1,
  "PriceAmounts": [
    {
      "ItemId": "{{TreasureChestCurrencyID}}",
      "Amount": 1
    }
  ]
}
```

호출이 성공하면 플레이어의 인벤토리가 업데이트됩니다. Treasure Chest 토큰 1개가 차감되고 번들의 콘텐츠(Legendary Sword 1개 + Gold 100개)가 추가됩니다.

## 여러 컨테이너 유형

이 패턴을 반복해 여러 컨테이너 유형을 만듭니다. 예:

| 컨테이너           | 화폐 (FriendlyId) | 번들 콘텐츠                              |
| -------------- | --------------- | ----------------------------------- |
| Treasure Chest | `tc`            | Legendary Sword 1개 + Gold 100개      |
| Supply Crate   | `sc`            | Health Potion 5개 + Mana Potion 3개   |
| Premium Box    | `pb`            | Rare Mount 1개 + Gold 500개 + Gem 50개 |

각 컨테이너 유형은 고유한 화폐와 번들을 가집니다.

## 컨테이너 구매에 스토어 사용

[스토어](/services/playfab/economy-monetization/economy-v2/catalog/stores)를 사용해 컨테이너 번들의 가격을 재정의합니다. 스토어를 사용하면 서로 다른 컨텍스트에서 동일한 컨테이너를 다양한 가격으로 제공할 수 있습니다(예: 이벤트 기간 동안 할인된 "열기" 비용).

```json theme={null}
{
  "Item": {
    "Type": "store",
    "Title": {
      "NEUTRAL": "Event Store"
    },
    "ItemReferences": [
      {
        "Id": "{{TreasureChestContentsBundleID}}",
        "Amount": 1,
        "PriceOptions": {
          "Prices": [
            {
              "Amounts": [
                {
                  "ItemId": "{{TreasureChestCurrencyID}}",
                  "Amount": 1
                }
              ]
            }
          ]
        }
      }
    ]
  },
  "Publish": true
}
```

그런 다음 구매 시 `StoreId`를 전달합니다.

```json theme={null}
{
  "Entity": {
    "Type": "title_player_account",
    "Id": "{{PlayerID}}"
  },
  "Item": {
    "Id": "{{TreasureChestContentsBundleID}}"
  },
  "Amount": 1,
  "PriceAmounts": [
    {
      "ItemId": "{{TreasureChestCurrencyID}}",
      "Amount": 1
    }
  ],
  "StoreId": "{{EventStoreID}}"
}
```

## 제한 사항

이 패턴은 **고정된 결정론적 콘텐츠**를 가진 컨테이너에 사용됩니다. 컨테이너를 열 때마다 콘텐츠가 달라지는(드롭 테이블과 짝을 이룬 v1 컨테이너와 유사한) **무작위 루트**가 필요한 경우 [드롭 테이블 및 무작위 루트](/services/playfab/economy-monetization/economy-v2/tutorials/drop-tables-and-randomized-loot) 튜토리얼을 참조하세요. 이 튜토리얼은 [Azure Functions](https://learn.microsoft.com/en-us/azure/azure-functions/functions-overview)를 사용해 다음을 수행합니다.

1. 플레이어의 인벤토리에서 컨테이너 토큰을 차감합니다.
2. 가중 무작위 선택 로직을 실행합니다.
3. 인벤토리 API를 통해 결과 아이템을 부여합니다.

## 참고 항목

* [Economy v2 번들](/services/playfab/economy-monetization/economy-v2/catalog/bundles)
* [Economy v2 스토어](/services/playfab/economy-monetization/economy-v2/catalog/stores)
* [가상 화폐](/services/playfab/economy-monetization/economy-v2/tutorials/currencies)
* [Economy v2 개요](/services/playfab/economy-monetization/economy-v2/overview)
* [PurchaseInventoryItems API 참조](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/purchase-inventory-items)
* [AddInventoryItems API 참조](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/add-inventory-items)