Catalog v2 快速入門

Economy v2 現已正式推出。如需支援和提供意見反應，請前往 PlayFab 論壇。

熟悉 Game Manager 之後，您可以：

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

如需 Unity 中的詳細逐步解說，請參閱 Unity 專屬教學課程。

第 1 部分：目錄概觀

步驟 1 – 取得權限

第一步是在 Game Manager UI 的 ⚙️ Title Settings > Economy (V2) 下的設定頁面中啟用目錄。您可以使用 UpdateCatalogConfig API，並將 IsCatalogEnabled 旗標設定為 true。若要與目錄互動，您需要登入 Game Manager 並使用網站工具，或是取得 Entity Token 以使用 API。取得實體權杖最簡單的方式是使用 GetEntityToken API。

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

API

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

C# SDK

// 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,
    };
}

以遊戲管理員身分呼叫時 (也就是沒有來自使用者登入的 SessionTicket)，最佳做法是包含 CustomTags 項目，記錄是誰發出呼叫，無論是您、伺服器還是自動化指令碼。這可讓您在查詢 PlayFab 記錄時，更容易追蹤變更並找出問題。

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

目錄設定包含許多不同的組態，從內容類型到使用者產生內容都有。您可以透過 API 更新和擷取所有設定，並在 Game Manager 中輕鬆以視覺化方式檢視其中許多設定。

Game Manager

在 Game Manager 中，前往 ⚙️ Title Settings > Economy。
在 Catalog (V2) 索引標籤下，前往 Catalog Settings
建立預設的 Content Type (建立 “Game Item” 類型是不錯的起點)。

API

呼叫 Catalog/GetCatalogConfig 方法，然後使用目錄類型透過 UpdateCatalogConfig 更新目錄的 ContentTypes 陣列。

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 內容類型之遊戲的傳回承載範例：

{
    "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。

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

{
  "NEUTRAL": "My Game Item",
  "en-US": "My Game Item"
}

API

呼叫 CreateDraftItem 端點以建立「草稿」目錄項目：

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

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

資料：

{
  "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

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

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

項目處於草稿狀態後，您就可以使用 PublishDraftItem 端點將其推送至「已發佈」狀態 (此步驟在 GameManager 中會以不可見的方式處理)。項目發佈後，即可搜尋並公開使用。您需要使用 CreateDraftItem 回應所傳回的 ItemId 才能發佈。

步驟 4 - 執行搜尋

Publish 呼叫成功後，即可使用先前發佈的 ItemId 和 SearchItems 端點搜尋項目。Catalog/Search API 會使用提供給 API 的一組參數對已發佈的目錄執行搜尋，並傳回一組分頁結果。

Game Manager

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

API

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

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

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

Catalog/search 的 filter、orderBy 和 select 欄位使用 OData 作為查詢標準。

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

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

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

步驟 1：建立貨幣

虛擬貨幣是遊戲內經濟體系的基礎。玩家和角色可以獲得這些貨幣，然後用來購買或交易項目。項目的成本可以是虛擬貨幣或真實貨幣。每個遊戲都可以支援多種任意的虛擬貨幣。貨幣為您的遊戲提供彈性，可實作您想要的任何交易媒介 (例如金幣、寶石、愛心或星際點數)。

Game Manager

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

API

使用下列項目呼叫 CreateDraftItem 端點並將類型設定為 “currency”，以建立草稿貨幣目錄項目：

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

使用 CreateDraftItem 傳回的 ItemId 呼叫 PublishItem。

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

資料：

{ 
  "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}}"
  }
}

對類型 ‘currency’ 執行 Catalog/Search 會傳回您已定義的所有貨幣。

步驟 2 - 授與貨幣

Game Manager

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

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

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

API

您可以呼叫 AddInventoryItems，將貨幣新增至實體錢包。根據預設，您需要使用遊戲層級實體驗證，才能任意將虛擬貨幣新增至玩家的庫存。

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

步驟 3 - 更新目錄項目

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

GameManager

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

API

呼叫 GetDraftItem 端點以取得目錄項目的草稿。然後使用下列項目，透過 UpdateDraftItem 端點更新草稿：

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

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

資料：

{
  "Id": "{{EntityID}}",
  "CustomTags": {
    "user": "{{Email}}"
  }
}

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

{
  "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 將其推送至已發佈狀態。項目發佈後，即可搜尋並公開使用。您需要使用 GetDraftItem 回應所傳回的 “itemId” 才能發佈。

XBOX Services

PlayFab

快速入門

Catalog v2 快速入門

第 1 部分：目錄概觀

步驟 1 – 取得權限

API

C# SDK

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

Game Manager

API

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

GameManager

API

C# SDK

步驟 4 - 執行搜尋

Game Manager

API

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

步驟 1：建立貨幣

Game Manager

API

步驟 2 - 授與貨幣

Game Manager

API

步驟 3 - 更新目錄項目

GameManager

API

另請參閱

​Catalog v2 快速入門

​第 1 部分：目錄概觀

​步驟 1 – 取得權限

​API

​C# SDK

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

​Game Manager

​API

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

​GameManager

​API

​C# SDK

​步驟 4 - 執行搜尋

​Game Manager

​API

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

​步驟 1：建立貨幣

​Game Manager

​API

​步驟 2 - 授與貨幣

​Game Manager

​API

​步驟 3 - 更新目錄項目

​GameManager

​API

​另請參閱

Catalog v2 快速入門

第 1 部分：目錄概觀

步驟 1 – 取得權限

API

C# SDK

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

Game Manager

API

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

GameManager

API

C# SDK

步驟 4 - 執行搜尋

Game Manager

API

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

步驟 1：建立貨幣

Game Manager

API

步驟 2 - 授與貨幣

Game Manager

API

步驟 3 - 更新目錄項目

GameManager

API

另請參閱