目录 v2 快速入门

重要

Economy v2 现已正式发布。 有关支持和反馈，请转到 PlayFab 论坛。

熟悉 Game Manager 后，可以执行以下操作：

1. 设置 v2 目录的权限、设置和项。
2. 设置收据验证
3. 演练如何购买物品

有关 Unity 中的详细演练，请参阅特定于 Unity 的教程。

第 1 部分：目录概述

步骤 1 - 获取权限

第一步是在游戏管理器 UI 的设置页面中的 ⚙️“游戏设置”>“Economy (V2)”下启用目录。 可以使用 UpdateCatalogConfig API 并将 IsCatalogEnabled 标志设置为 true。

若要与目录交互，需要登录到 GameManger 并使用站点工具，或者获取用于使用 API 的实体令牌。 获取实体令牌最简单的方法是使用 GetEntityToken API。

注意

若要以管理员或权威服务的身份调用 API（在创建第一个目录项之前需要执行此操作），需要包含带有游戏密钥的 X-SecretKey 标头。 可以在游戏管理器 UI 的 ⚙️“游戏设置”>“密钥”下创建游戏密钥。

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

1. 在游戏管理器中，导航到 ⚙️“游戏设置”>“Economy”。
2. 在“目录 (V2)”选项卡下，转到“目录设置”
3. 创建默认内容类型（创建“游戏物品”类型是一个很好的起点）。

API

调用 Catalog/GetCatalogConfig 方法，然后使用特定目录类型对目录ContentTypes 数组进行 UpdateCatalogConfig 更新。

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”>“目录 (V2)”。

在“项”选项卡下，选择“新建项”。

填写所需的元数据 - 只有四个必需属性（Creator Type、Title、Start date 和 Content type）。 选择“发布”。

提示

创建者类型默认为“游戏”，尽管可能存在玩家为游戏创建物品的情况。 在这种情况下，请选择“title_player_account”。 具有“编辑 JSON”选项的字段由元数据（例如默认为“中性”的本地化语言）键。 所有日期均以 UTC 表示。

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

API

通过调用 CreateDraftItem 终结点创建“草稿”目录项：

• X-EntityToken 标头中的 EntityToken（来自 GetEntityToken 或其他 PlayFab login 调用）
• 项 CreatorEntity.Id 中的 Playfab 游戏 ID

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 - 执行搜索

发布调用成功后，可以使用以前发布的 ItemId 和 SearchItems 终结点搜索项。 目录/搜索 API 使用提供给 API 的一组参数针对已发布目录执行搜索，并返回一组分页结果。

Game Manager

Game Manager 搜索是一目了然的，并且存在于每个目录 v2 页面上。 “已发布”和“草稿”筛选器位于顶部。 选择“搜索”按钮旁边的“筛选器（漏斗）”图标以查看筛选器列表。 选择 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
}

保存返回的 ID 用于本快速入门中后面的操作。

注意

目录/搜索筛选器、orderBy 和 select 字段使用 OData 作为查询标准。

第 2 部分：物品栏和虚拟货币概述

物品栏物品和虚拟货币是 PlayFab 为玩家实体提供的两个游戏内虚拟物品“桶”。 过程如下：

1. 设置初始虚拟货币
2. 创建具有虚拟货币成本的物品
3. 将物品添加到玩家的物品栏

步骤 1：创建货币

虚拟货币是游戏内经济的基础。 玩家和角色可以获得这些货币，然后用它们购买或交易物品。

物品可以具有以虚拟货币或实际货币表示的成本。 每款游戏可以支持多种任意的虚拟货币。 货币为游戏提供了灵活性，让你能够实现所需的任何交换媒介（例如黄金、宝石、红心或星际信用）。

Game Manager

1. 打开游戏管理器，转到“Economy”>“目录 (V2)”。
2. 选择 Currency 选项卡。
3. 选择“新建货币”，设置“开始日期”，为“中性”键设置人类可理解的“标题”，并在“友好 ID”字段中输入此货币的唯一货币代码。
4. 选择“保存草稿”。 项 ID 用作草稿货币代码。
5. 单击货币列表中的“草稿”筛选器，查看新货币。
6. 再次编辑货币，然后选择“保存并发布”。 易记 ID 用作已发布的货币代码。

API

使用以下方法调用类型设置为“currency”的 CreateDraftItem 终结点，创建草稿货币目录项：

• 具有目录权限的 EntityToken
• 作为项“创建者”的 Entity.Id
• Playfab 游戏 ID
• 项应为“Currency”类型的捆绑包，并包含标题和说明

使用 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”将返回已定义的所有货币。

步骤 2 - 授予货币

Game Manager

实体玩家需要虚拟货币才能进行购买。

1. 打开 GameManager，导航到“玩家”，然后选择“搜索”以检索玩家列表。
2. 选择要向其授予货币的玩家 ID。
3. 选择“物品栏 (V2)”选项卡。
4. 筛选至“货币”类型，然后选择“选取多个项”以查看货币的完整列表。
5. 选择创建的货币，并为实体玩家输入新金额。
6. 选择“保存”。

警告

公开玩家货币授予的页面目前不在 GameManager 中。 请参阅路线图。

API

可以调用 AddInventoryItems 将货币添加到实体钱包。 默认情况下，需要使用游戏级实体身份验证任意向玩家的物品栏添加虚拟货币。

注意

AddInventoryItems 被视为游戏管理员调用，通常不是游戏客户端直接调用的内容。

步骤 3 - 更新目录项

项必须具有货币值才能使用虚拟货币购买。

GameManager

1. 打开游戏管理器，然后导航到 Economy。
2. 选择“目录 (V2)”选项卡，并确保已筛选至“已发布”项。
3. 选择之前创建的项的标题。
4. 选择“编辑草稿项”。
5. 选择“➕ 添加新价格”，然后通过选择创建的“货币”项来设置金额。 选择“添加”完成。
6. 选择“保存并发布”。

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 才能进行发布。

另请参阅

• Economy v2 概述
• 设置
• 商店