> ## 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.

# 快速入門

> PlayFab Economy v2 快速入門，說明如何在 Game Manager 中設定 Catalog v2、設定權限、新增項目，以及啟用收據驗證。

# Catalog v2 快速入門

<Info>
  Economy v2 現已正式推出。如需支援和提供意見反應，請前往 [PlayFab 論壇](https://community.playfab.com)。
</Info>

熟悉 Game Manager 之後，您可以：

1. 設定 v2 目錄的權限、設定和項目。
2. 設定收據驗證
3. 逐步完成購買項目

如需 Unity 中的詳細逐步解說，請參閱 [Unity 專屬教學課程](/zh-TW/services/playfab/economy-monetization/economy-v2/tutorials/getting-started-with-unity-and-android)。

## 第 1 部分：目錄概觀

### 步驟 1 – 取得權限

第一步是在 Game Manager UI 的 ⚙️ **Title Settings** > **Economy (V2)** 下的設定頁面中啟用目錄。您可以使用 `UpdateCatalogConfig` API，並將 `IsCatalogEnabled` 旗標設定為 true。

若要與目錄互動，您需要登入 Game Manager 並使用網站工具，或是取得 Entity Token 以使用 API。取得實體權杖最簡單的方式是使用 [GetEntityToken](https://learn.microsoft.com/en-us/rest/api/playfab/authentication/authentication/get-entity-token) API。

<Note>
  若要以管理員或權威服務的身分呼叫 API (在建立第一個目錄項目之前，您必須這麼做)，您需要包含具有遊戲秘密金鑰的 X-SecretKey 標頭。您可以在 Game Manager UI 的 ⚙️ **Title Settings** > **Secret Keys** 下建立遊戲秘密金鑰。
</Note>

#### API

```bash theme={null}
curl \
  -H "X-SecretKey: {{SecretKey}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{titleId}}.playfabapi.com/Authentication/GetEntityToken \
  -d "{\"CustomTags\": {\"user\": \"{{email}}\"}}"
```

#### C# SDK

```csharp theme={null}
// ENABLE_PLAYFABSERVER_API symbol denotes this is an admin-level game server and not a game client.
private static async Task PlayFabEconomyv2QuickStart()
{
#if ENABLE_PLAYFABSERVER_API
    string systemGUID = Environment.GetEnvironmentVariable("SYSTEM_GUID", EnvironmentVariableTarget.Process);
    PlayFabSettings.staticSettings.DeveloperSecretKey =
        Environment.GetEnvironmentVariable("PLAYFAB_SECRET_KEY", EnvironmentVariableTarget.Process);

#endif
    PlayFabSettings.staticSettings.TitleId =
        Environment.GetEnvironmentVariable("PLAYFAB_TITLE_ID", EnvironmentVariableTarget.Process);
    PlayFab.EconomyModels.EntityKey gameEntityKey = new()
    {
        Type = "title",
        Id = PlayFabSettings.staticSettings.TitleId
    };

    PlayFabResult<GetEntityTokenResponse> gameTokenRequest = null;
    try
    {
        gameTokenRequest = await PlayFabAuthenticationAPI.GetEntityTokenAsync(new GetEntityTokenRequest()
        {
            CustomTags = new Dictionary<string, string>
            {
#if ENABLE_PLAYFABSERVER_API
                { "server", systemGUID }
#endif
            }
        });
        if (gameTokenRequest.Error != null)
        {
            throw new Exception(gameTokenRequest.Error.GenerateErrorReport());
        }
    }
    catch (Exception e)
    {
        Console.WriteLine(string.Format("PlayFab Auth Error: {0}", e));
        return;
    }

    PlayFabAuthenticationContext gameAuthContext = new()
    {
        EntityToken = gameTokenRequest.Result.EntityToken,
    };
}
```

***

<Tip>
  以遊戲管理員身分呼叫時 (也就是沒有來自使用者登入的 [SessionTicket](https://learn.microsoft.com/en-us/rest/api/playfab/server/authentication/authenticate-session-ticket))，最佳做法是包含 *CustomTags* 項目，記錄是誰發出呼叫，無論是您、伺服器還是自動化指令碼。這可讓您在查詢 PlayFab 記錄時，更容易追蹤變更並找出問題。
</Tip>

### 步驟 2 - 設定您的目錄設定

[目錄設定](/zh-TW/services/playfab/economy-monetization/economy-v2/settings)包含許多不同的組態，從內容類型到使用者產生內容都有。您可以透過 API 更新和擷取所有設定，並在 Game Manager 中輕鬆以視覺化方式檢視其中許多設定。

#### Game Manager

1. 在 [Game Manager](/zh-TW/services/playfab/live-service-management/gamemanager) 中，前往 ⚙️ **Title Settings** > **Economy**。
2. 在 **Catalog (V2)** 索引標籤下，前往 **Catalog Settings**
3. 建立預設的 *Content Type* (建立 "Game Item" 類型是不錯的起點)。

#### API

呼叫 [Catalog/GetCatalogConfig](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/get-catalog-config) 方法，然後使用目錄類型透過 [UpdateCatalogConfig](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/update-catalog-config) 更新目錄的 ContentTypes 陣列。

```bash theme={null}
curl \
  -H "X-SecretKey: {{SecretKey}}" \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/GetCatalogConfig \
  -d "{\"CustomTags\": {\"user\": \"{{Email}}\"}}"

curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/UpdateCatalogConfig \
  -d "{\"Config\": {{{CatalogConfig}}}, \"CustomTags\": {\"user\": \"{{Email}}\"}}"
```

具有一些目錄和 UGC 內容類型之遊戲的傳回承載範例：

```json theme={null}
{
    "code": 200,
    "status": "OK",
    "data": {
        "Config": {
            "IsCatalogEnabled": true,
            "AdminEntities": [...],
            "Catalog": {
                "ContentTypes": [
                    "gameitem",
                    "enemy",
                    "weapon",
                    "armor",
                    "levelupstats"
                ],
                "Tags": [...]
            },
            "DeepLinkFormats": [],
            "DisplayPropertyIndexInfos": [
                {
                    "Name": "TestSearchable",
                    "Type": "SearchString"
                }
            ],
            "ReviewerEntities": [],
            "UserGeneratedContent": {
                "ContentTypes": [
                    "weapon",
                    "armor"
                ],
                "Tags": [...]
            },
            ...
        }
    }
}
```

***

### 步驟 3 - 將項目發佈至目錄

#### GameManager

前往 **Economy** > **Catalog (V2)**。

在 **Items** 索引標籤下，選取 **New Item**。

填寫必要的中繼資料，只有四個必要屬性 (*Creator Type*、*Title*、*Start date* 和 *Content type*)。選取 **Publish**。

<Tip>
  Creator Type 預設為 "title"，不過在某些情況下，可能是玩家為您的遊戲建立項目。在此情況下，您會選取 "title\_player\_account"。具有 *Edit JSON* 選項的欄位是以中繼資料 (例如當地語系化語言，預設為 "neutral") 作為索引鍵。所有日期均為 UTC。
</Tip>

```json theme={null}
{
  "NEUTRAL": "My Game Item",
  "en-US": "My Game Item"
}
```

#### API

呼叫 [CreateDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/create-draft-item) 端點以建立「草稿」目錄項目：

* X-EntityToken 標頭中的 EntityToken (來自 GetEntityToken 或其他 PlayFab `login` 呼叫)
* 項目 CreatorEntity.Id 中的 PlayFab 遊戲識別碼

```bash theme={null}
curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/CreateDraftItem \
  -d "{{Data}}"
```

資料：

```json theme={null}
{
  "Item": {
    "CreatorEntity": {
      "Id": "{{TitleID}}",
      "Type": "title"
    },
    "Type": "catalogItem",
    "ContentType": "gameitem",
    "Title": {
      "NEUTRAL": "My Amazing Fire Sword",
      "en-US": "My Lit Lit Sword"
    },
    "StartDate": "2023-07-27T00:00:00.000Z",
    "Tags": [
      "weapon"
    ]
  },
  "Publish": true,
  "CustomTags": {
    "user": "{{Email}}"
  }
}
```

#### C# SDK

```csharp theme={null}
private static async Task PlayFabEconomyv2QuickStart()
{
    // Continued from above example...
    CreateDraftItemRequest gameFireItem = new()
    {
        AuthenticationContext = gameAuthContext,
        Item = new CatalogItem()
        {
            CreatorEntity = gameEntityKey,
            Type = "catalogItem",
            ContentType = "gameitem",
            Title = new Dictionary<string, string>
            {
                { "NEUTRAL", "My Amazing Fire Sword" },
                { "en-US", "My Lit Lit Sword" }
            },
            StartDate = DateTime.Now,
            Tags = new List<string>
            {
              "weapon"
            }
        },
        Publish = true,
        CustomTags = new Dictionary<string, string>
        {
            { "server", systemGUID }
        }
    };
    PlayFabResult<CreateDraftItemResponse> gameDraftItemResponse = null;
    try
    {
        gameDraftItemResponse = await PlayFabEconomyAPI.CreateDraftItemAsync(gameFireItem);
        if (gameDraftItemResponse.Error != null)
        {
            throw new Exception(gameDraftItemResponse.Error.GenerateErrorReport());
        }
    }
    catch (Exception e)
    {
        Console.WriteLine(string.Format("PlayFab CreateDraftItem Error: {0}", e));
        return;
    }
    Console.WriteLine(string.Format("PlayFab CreateDraftItem Success: {0}",
        JsonConvert.SerializeObject(gameDraftItemResponse.Result, Formatting.Indented)));
}
```

***

<Note>
  不一定要將項目置於草稿狀態，草稿狀態適用於您預期會在一段時間內反覆修改中繼資料的情況。我們支援 "publish" 參數，將其設定為 "true" 時會立即發佈項目。視您的模式而定，這可以為您節省一些呼叫量。
</Note>

項目處於草稿狀態後，您就可以使用 [PublishDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/publish-draft-item) 端點將其推送至「已發佈」狀態 (此步驟在 GameManager 中會以不可見的方式處理)。項目發佈後，即可搜尋並公開使用。您需要使用 CreateDraftItem 回應所傳回的 ItemId 才能發佈。

### 步驟 4 - 執行搜尋

Publish 呼叫成功後，即可使用先前發佈的 ItemId 和 [SearchItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/search-items) 端點搜尋項目。Catalog/Search API 會使用提供給 API 的一組參數對已發佈的目錄執行搜尋，並傳回一組分頁結果。

#### Game Manager

Game Manager 搜尋一目了然，存在於每個 Catalog v2 頁面上。*Published* 和 *Draft* 篩選位於頂端。選取 *Search* 按鈕旁的 *Filters (Funnel)* 圖示，即可查看篩選清單。選取 `Enter ODATA filter` 以新增 OData 篩選。

#### API

```bash theme={null}
curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/SearchItems \
  -d "{{Data}}"
```

```json theme={null}
{
  "Search": "Fire",
  "Filter": "tags/any(t:t eq 'desert') and contentType eq 'gameitem'",
  "OrderBy": "lastModifiedDate asc",
  "ContinuationToken": "abc=",
  "Count": 2
}
```

儲存傳回的識別碼，以供本快速入門稍後使用。

***

<Note>
  Catalog/search 的 filter、orderBy 和 select 欄位使用 [OData](https://learn.microsoft.com/en-us/odata/concepts/queryoptions-overview) 作為查詢標準。
</Note>

## 第 2 部分：庫存和虛擬貨幣概觀

庫存項目和虛擬貨幣是 PlayFab 為玩家實體支援的兩種遊戲內虛擬物品「容器」。流程如下：

1. 設定初始虛擬貨幣
2. 建立具有虛擬貨幣成本的項目
3. 將項目新增至玩家的庫存

### 步驟 1：建立貨幣

虛擬貨幣是遊戲內經濟體系的基礎。玩家和角色可以獲得這些貨幣，然後用來購買或交易項目。

項目的成本可以是虛擬貨幣或真實貨幣。每個遊戲都可以支援多種任意的虛擬貨幣。貨幣為您的遊戲提供彈性，可實作您想要的任何交易媒介 (例如金幣、寶石、愛心或星際點數)。

#### Game Manager

1. 開啟 Game Manager 並前往 **Economy** > **Catalog (V2)**。
2. 選取 **Currency** 索引標籤。
3. 選擇 **New Currency**，設定 *Start date*、"neutral" 索引鍵的人類可讀 *Title*，並在 *Friendly ID* 欄位中輸入此貨幣的唯一貨幣代碼。
4. 選取 **Save as draft**。Item ID 會作為草稿貨幣代碼使用。
5. 在貨幣清單中選取 **Draft** 篩選，以檢視您的新貨幣。
6. 再次編輯貨幣，然後選取 **Save and publish**。Friendly ID 會作為已發佈的貨幣代碼使用。

#### API

使用下列項目呼叫 [CreateDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/create-draft-item) 端點並將類型設定為 "currency"，以建立草稿貨幣目錄項目：

* 具有目錄權限的 EntityToken
* 作為項目 'Creator' 的 Entity.Id
* PlayFab 遊戲識別碼
* 項目應該是類型為 'Currency' 的套件組合，並包含 Title 和 Description

使用 CreateDraftItem 傳回的 ItemId 呼叫 PublishItem。

```bash theme={null}
curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/CreateDraftItem \
  -d "{{Data}}"
```

資料：

```json theme={null}
{ 
  "Item": {
    "CreatorEntity": {
      "Id": "{{TitleID}}",
      "Type": "title"
    },
    "Type": "currency",
    "ContentType": "gameitem",
    "AlternateIds": [
      { 
        "Type": "FriendlyId",
        "Value": "TC"
      } 
    ],
    "Title": {
      "NEUTRAL": "My Amazing Test Currency",
      "en-US": "My Test Coin"
    },
    "StartDate": "2023-07-27T00:00:00.000Z"
  },
  "Publish": true,
  "CustomTags": {
    "user": "{{Email}}"
  }
}
```

***

<Tip>
  對類型 'currency' 執行 Catalog/Search 會傳回您已定義的所有貨幣。
</Tip>

### 步驟 2 - 授與貨幣

#### Game Manager

您的實體玩家需要虛擬貨幣才能進行購買。

1. 開啟 GameManager，前往 Players，然後選取 **Search** 以擷取玩家清單。
2. 選取您要授與貨幣的玩家識別碼。
3. 選取 **Inventory (V2)** 索引標籤。
4. 篩選為 "Currency" **Type**，然後選取 **Pick multiple items** 以檢視完整的貨幣清單。
5. 選擇您建立的 *Currency*，並為實體 *Player* 輸入新的數量。
6. 選取 **Save**。

<Warning>
  公開玩家貨幣授與的頁面目前不在 GameManager 中。
</Warning>

#### API

您可以呼叫 [AddInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/add-inventory-items)，將貨幣新增至實體錢包。根據預設，您需要使用遊戲層級實體驗證，才能任意將虛擬貨幣新增至玩家的庫存。

***

<Note>
  *AddInventoryItems* 被視為遊戲管理員呼叫，通常不會由遊戲用戶端直接呼叫。
</Note>

### 步驟 3 - 更新目錄項目

項目必須具有貨幣值，才能以虛擬貨幣購買。

#### GameManager

1. 開啟 Game Manager 並前往 **Economy**。
2. 選取 **Catalog (V2)** 索引標籤，並確定已篩選為 **Published** 項目。
3. 選取您先前建立之項目的標題。
4. 選取 **Edit draft item**。
5. 選取 **➕ Add new price**，並選取您建立的貨幣項目以設定 *Amount*。選取 **Add** 以完成。
6. 選取 **Save and Publish**。

#### API

呼叫 [GetDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/get-draft-item) 端點以取得目錄項目的草稿。然後使用下列項目，透過 [UpdateDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/update-draft-item) 端點更新草稿：

* X-EntityToken 標頭中的 EntityToken (來自 GetEntityToken 或其他 PlayFab `login` 呼叫)
* 項目 EntityKey.Id 中來自先前呼叫的 Entity.Id

```bash theme={null}
curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/GetDraftItem \
  -d "{{Data}}"
```

資料：

```json theme={null}
{
  "Id": "{{EntityID}}",
  "CustomTags": {
    "user": "{{Email}}"
  }
}
```

```bash theme={null}
curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/UpdateDraftItem \
  -d "{{Data}}"
```

```json theme={null}
{
  "Item": {
    "Id": "{{EntityID}}",
    "CreatorEntity": {
      "Id": "{{TitleID}}",
      "Type": "title"
    },
    "Type": "catalogItem",
    "ContentType": "gameitem",
    "Title": {
      "NEUTRAL": "My Amazing Fire Sword",
      "en-US": "My Lit Lit Sword"
    },
    "StartDate": "2023-07-27T00:00:00.000Z",
    "Tags": [
      "weapon"
    ]
    "PriceOptions": {
      "Prices": [
        {
          "Amounts": [
            {
              "ItemId": "{{CurrencyID}}",
              "Amount": 15
            }
          ]
        }
      ]
    }
  },
  "Publish": true,
  "CustomTags": {
    "user": "{{Email}}"
  }
}
```

如果您未將 `Publish` 設定為 `true`，則必須使用 [PublishDraftItem](https://learn.microsoft.com/en-us/rest/api/playfab/economy/catalog/publish-draft-item) 將其推送至已發佈狀態。項目發佈後，即可搜尋並公開使用。您需要使用 GetDraftItem 回應所傳回的 "itemId" 才能發佈。

## 另請參閱

* [Economy v2 概觀](/zh-TW/services/playfab/economy-monetization/economy-v2/overview)
* [設定](/zh-TW/services/playfab/economy-monetization/economy-v2/settings)
* [商店](/zh-TW/services/playfab/economy-monetization/economy-v2/catalog/stores)


## Related topics

- [Party 快速入門](/zh-TW/services/playfab/multiplayer/networking/quickstart.md)
- [Android 快速入門](/zh-TW/services/playfab/sdks/c/quickstart-android.md)
- [GDK 快速入門](/zh-TW/services/playfab/sdks/c/quickstart-gdk.md)
- [iOS 快速入門](/zh-TW/services/playfab/sdks/c/quickstart-ios.md)
- [Linux 快速入門](/zh-TW/services/playfab/sdks/c/quickstart-linux.md)