第 3 部分 - 编码 + 示例

现在你已准备好环境并熟悉 Game Manager，我们可以开始编码游戏了。

先决条件

步骤 1 - 配置环境设置

我们建议你在开始编码后做的第一件事是配置你的环境设置。这样你就可以放心地知道你所做的每个调用都将链接到你的 Title 并使用你的特定 Developer Secret Key。要完成此步骤，你可以在代码中的任何位置（希望是你容易找到的地方）指定 TitleId 和 DeveloperSecretKey 变量并为它们分配值。通过添加两行单独的代码来做到这一点，如下所示：

PlayFabSettings.staticSettings.TitleId = "{Your Title ID}";
PlayFabSettings.staticSettings.DeveloperSecretKey = "{Your Developer Secret Key}";

步骤 2 - 进行身份验证

一旦你设置了环境、在你的项目中安装并配置了 PlayFab NuGet 包，并创建了你的 Studio 和 Title，我们就可以开始编码我们的身份验证了。

用户可以通过多种方式进行身份验证。在此示例中，我们将使用 LoginWithCustomId 方法。还有其他进行身份验证的方法，包括平台特定的方法。有关更多信息，请访问 Login Basics。

接下来是使用 C# 编写的示例代码，其中我们使用 LoginWithCustomID 对用户进行身份验证，这被归类为匿名登录。在调用 API 进行身份验证之前，我们必须首先声明一个全局变量，用于存储作为登录过程一部分生成的 EntityKey。 EntityKey 用于对 API 进行任何类型的调用，并且是将每个请求和响应链接到已登录用户的关键。全局 EntityKey 变量的声明如下：

private static PlayFab.ClientModels.EntityKey entityKey;

然后，让用户进行身份验证的逻辑是：

C# SDK

var request = new LoginWithCustomIDRequest { CustomId = username };
var loginTask = PlayFabClientAPI.LoginWithCustomIDAsync(request);
entityKey = loginTask.Result.Result.EntityToken.Entity;

API

{
  "CustomId": "{{Username}}",
  "CreateAccount": false,
  "TitleId": "{{TitleId}}"
}

以上代码查找链接到你的游戏 title 的任何现有玩家。但如果没有具有匹配用户名的用户，它将失败。要绕过这一点，我们可以向请求正文添加 “CreateAccount = true” 参数。这使得如果没有与用户发送的用户名匹配的用户，PlayFab 会创建一个新的玩家。这将导致代码如下所示：

C# SDK

var request = new LoginWithCustomIDRequest { CustomId = username, CreateAccount = true };
var loginTask = PlayFabClientAPI.LoginWithCustomIDAsync(request);
entityKey = loginTask.Result.Result.EntityToken.Entity;

API

{
  "CustomId": "{{Username}}",
  "CreateAccount": true,
  "TitleId": "{{TitleId}}"
}

成功登录后，API 将返回一些数据集，例如 SessionTicket、用户的 PlayFab ID 和 EntityToken。这些可以从 API 的直接响应中看到，详情如下。

{
    "code": 200,
    "status": "OK",
    "data": {
        "SessionTicket": "{{SessionTicket}}",
        "PlayFabId": "{{PlayFabID}}",
        "NewlyCreated": false,
        "SettingsForUser": {
            "NeedsAttribution": false,
            "GatherDeviceInfo": true,
            "GatherFocusInfo": true
        },
        "LastLoginTime": "2023-08-01T17:09:54.508Z",
        "EntityToken": {
            "EntityToken": "{{EntityToken}}",
            "TokenExpiration": "2023-08-04T21:20:35Z",
            "Entity": {
                "Id": "{{Player ID}}",
                "Type": "title_player_account",
                "TypeString": "title_player_account"
            }
        },
        "TreatmentAssignment": {
            "Variants": [],
            "Variables": []
        }
    }
}

一旦你从 API 获得 "code":200 返回，或者从上面的 C# 示例中的 loginTask 获得信息，你就已通过身份验证，可以继续下一步了！

步骤 3 - 设置你的起始库存

现在你已使用有效玩家登录（或创建了新玩家），你的第一步应该是设置该玩家的起始库存。为此，我们将使用 ExecuteInventoryOperations API 调用。

ExecuteInventoryOperations 调用允许我们在玩家的库存上执行多个/批量 InventoryOperations。支持的操作类型有：- Add - Delete - Purchase - Subtract - Transfer - Update

对于此示例，我们将添加与我们游戏对应的物品。它们是三个 Stone 实例、一个 Cream 实例和一个 Gold 实例（这假设你已创建了更多物品，如果没有，请在继续之前这样做）。但我们没有简单使用 Add 操作，而是使用 Purchase 操作，并且我们以免费的方式购买所需的实例。

要使此步骤正常工作，你必须首先在 Game Manager 中的你的 title 中创建物品。

下面的代码片段将向你展示如何在 C# 和使用 PlayFab 的 API 中批量进行这些调用。

C# SDK

在此 C# 示例中，你可以看到我们首先将 purchasePrice 设置为所有交易的标准值，这是因为我们将使它们的价格都为 0。任何一个物品都可以有多个价格，因此 purchasePrice 变量的类型为 List<PurchasePriceAmount>。你可能会注意到的下一个方面是，请求除了接受 InventoryOperation 列表外，还接受一个 Entity。为此，我们将使用我们之前从登录中获得的值创建一个新的 Entity。最后，每个 InventoryOperation 都接受一个 Purchase 值，尽管这可能是 ExecuteInventoryOperations 调用下可用的每一个（Add、Delete、Purchase、Subtract、Transfer 和 Update）。在本例中，我们使用 Purchase 标识符，因此我们需要一个 new PurchaseInventoryItemsOperation。你还需要清楚这是你要购买的物品。你通过使用 InventoryItemReference 来做到这一点，它以物品的 ID 作为其唯一参数。在我们的代码中，我们有一个名为 SearchItem({itemName}) 的方法，但你可以很容易地用表示物品 ID 的字符串替换它。确保将每个物品的名称（或 ID）与相应的数量匹配。

var purchasePrice = new List<PurchasePriceAmount> { new PurchasePriceAmount { ItemId = freeItemId, Amount = 0 } };
var request = new ExecuteInventoryOperationsRequest 
{ 
    Entity = new PlayFab.EconomyModels.EntityKey { Id = entityKey.Id, Type = entityKey.Type },
    Operations = new List<InventoryOperation> {
        new InventoryOperation
        {
            Purchase = new PurchaseInventoryItemsOperation { 
                Item = new InventoryItemReference {AlternateId = new AlternateId { Type = "FriendlyId", Value = "Stone" } }, 
                Amount = 3, 
                PriceAmounts = purchasePrice
            }
        },
        new InventoryOperation
        {
            Purchase = new PurchaseInventoryItemsOperation {
                Item = new InventoryItemReference { AlternateId = new AlternateId { Type = "FriendlyId", Value = "Gold" } },
                Amount = 1,
                PriceAmounts = purchasePrice
            }
        },``
        new InventoryOperation
        {
            Purchase = new PurchaseInventoryItemsOperation {
                Item = new InventoryItemReference {AlternateId = new AlternateId { Type = "FriendlyId", Value = "Cream" }},
                Amount = 1,
                PriceAmounts = purchasePrice
            }
        }
    }
};
await PlayFabEconomyAPI.ExecuteInventoryOperationsAsync(request);

在上述代码中，要在代码中成功使用 AlternateId 和 FriendlyId，你的物品必须在 Game Manager 中配置这些值。为此，我建议你查看第 2 部分 - 使用 Game Manager，其中我们详细说明了你应遵循的步骤。

API

使用下面显示的请求正文调用 ExecuteInventoryOperations API 端点。将 ID 替换为相应的 ID。请注意 Operations 是一个数组，你可以同时用多种类型的操作填充它。重要的是要理解，对于你进行的每个 API 调用，你必须使用特定于你的活动会话或已登录用户的 EntityToken 设置 X-EntityToken 头。换句话说，在进行任何 API 调用之前，你应首先 LoginWithCustomID（在此示例中）并从返回消息中获取 EntityToken 以用作所有 API 调用中的头。

{
  "Operations": [
    {
      "Purchase": {
            "Item": {
                "Id": {Stone ID}
            },
            "Amount": 3,
            "PriceAmounts": [
                {
                "ItemId": {Free Item ID},
                "Amount": 0
                }
            ]
        }
    },
    {
      "Purchase": {
            "Item": {
                "Id": {Gold ID}
            },
            "Amount": 1,
            "PriceAmounts": [
                {
                "ItemId": {Free Item ID},
                "Amount": 0
                }
            ]
        }
    },
    {
      "Purchase": {
            "Item": {
                "Id": {Cream ID}
            },
            "Amount": 1,
            "PriceAmounts": [
                {
                "ItemId": {Free Item ID},
                "Amount": 0
                }
            ]
        }
    }
  ]
}

下一个 JSON 是在进行上述调用后的成功返回消息示例。你会看到返回三个不同的交易 ID，因为 ID 是按每次修改给出的，尽管这并不意味着有三个单独的交易。相反，它是作为一个单个交易处理的，但具有三个修改，因此我们只对整个交易返回一个成功或失败，无论修改的数量如何。

{
    "code": 200,
    "status": "OK",
    "data": {
        "IdempotencyId": {Idempotency ID},
        "TransactionIds": [
            "200",
            "201",
            "202"
        ],
        "ETag": "1/MjAy"
    }
}

步骤 4 - 创建捆绑包

捆绑包允许你将多个物品分组为一个单一物品。有关捆绑包的更多信息，请参见我们的捆绑包文档，请访问此链接。对于我们的示例，我们将使用捆绑包对 Kitchen 返回的物品进行分组，这有助于我们维护 Icebox 物品。冰盒背后的想法是在购买冰淇淋时成为不可消耗的物品，即使冰盒是所需材料之一。其工作原理的高级概述如下。想象一个玩家，其库存中有一个 Cream 和一个 Icebox。一旦访问 Kitchen 商店，该玩家必须使用这两个物品来购买/制作一个 Ice Cream。鉴于 Icebox 是不可消耗的，预期的功能是产生一个包含一个 Ice Cream 和一个 Icebox 的库存，只消耗了一个 Cream 物品。我们在幕后处理它的方式是使用一个价格为一个 Icebox 和一个 Cream 的捆绑包，其返回物品是一个 Ice Cream 和一个 Icebox。这意味着玩家库存中的 Icebox 将被消耗，但消耗它的同一交易返回另一个，给玩家一种 Icebox 始终在库存中的印象，而实际上 Icebox 实例不同，但对玩家不可见。要创建捆绑包，你必须转到 title 的 Economy 部分，就像你在创建新物品时所做的那样。会有一个名为 Bundles 的选项卡，位于 Items、Currency 等选项卡旁边。选中后，屏幕右上角会出现一个蓝色按钮，上面写着 New bundle。然后将显示一个类似于创建新物品的表单，主要区别在于，如果你向下滚动，你会发现一个名为 Items 的部分。在这里你可以添加你希望捆绑包包含的物品，购买时这些物品将被转移到玩家的库存中。单击 Add 按钮后，会弹出目录中所有物品的可搜索列表，在这里你可以选择要包含在捆绑包中的物品。选定物品并添加后，你可以继续 Save and publish，你的捆绑包现在将处于活动状态，并可从商店中选择作为购买价格。

步骤 5 - 创建商店

按照我们的制作游戏示例，我们必须让玩家从商店购买物品。将有三个不同的商店（在本例中是地点），Science Machine、Alchemy Engine 和 Kitchen。我们将重点关注 Kitchen。在这里，玩家能够以 1 Cream 和 1 Icebox（应创建的新物品）的价格购买 Ice Cream（应创建的新物品）。之所以选择这个特殊情况，是因为它展示了捆绑包如何与商店和交易一起工作。商店只能通过 Game Manager 创建，方法是转到左侧导航栏的 Economy 部分，然后从不同的选项卡选项中选择 Stores 并选择蓝色 New store 按钮。这将显示一个类似于创建新物品时使用的表单，其中唯一必填的字段是 Start Date 和你想赋予商店的 Title。向下滚动，你将

步骤 6 - 向商店添加捆绑包

现在你已经创建并发布了你的捆绑包和商店。你可以将捆绑包作为可返回物品添加到你的商店。为此，进入你的商店，向下滚动直到看到 Items 标题并选择 Add 按钮。这会显示目录中的物品列表。在搜索栏的左侧，会有一个下拉菜单，其中包含不同类型的对象，例如 Items、UGC Items、Bundles 和 Subscription。如果你选择 Bundles，它会过滤列表以仅反映捆绑包类型的物品，在这里你应该会看到你之前创建的捆绑包。选择捆绑包名称旁边的 Add 按钮，然后选择窗口末尾的 Add 按钮，捆绑包将被添加为该特定商店的可能交易物品。在继续之前还有最后一步，为你的捆绑包设置价格。此价格与任何其他物品定价一样，需要玩家在其库存中拥有所需的任何价格物品，然后才能接受购买。要设置价格，你可以选择捆绑包右侧的 Add new price 按钮，从物品列表中选择你希望作为价格的物品。在我们的例子中，我们希望价格是 1 Icebox 和 1 Cream。现在你的捆绑包已添加到你的商店并已相应地定价，我们可以继续下一步。

步骤 7 - 购买捆绑包

一旦创建了你的捆绑包和商店，并且你的捆绑包已链接到你的商店，你现在可以购买该捆绑包并将结果物品放入你的库存。要从玩家的角度购买捆绑包，你可以使用 PlayFab API 的 PurchaseInventoryItems。它不仅适用于捆绑包，也适用于单个物品。

API

在以下情况中，我们希望以 1 Icebox 和 1 Cream 的价格购买 1 个捆绑包。我们将使用 PriceAmount 的数组属性将多个物品设置为价格。只需确保你给你的捆绑包一个 FriendlyId。

{
  "Item": {
    "AlternateId": {
        "Type": "FriendlyId",
        "Value": "Ice Cream and Ice Box"
    }
  },
  "Amount": 1,
  "PriceAmounts": [
    {
        "ItemId": "0d2ab329-2fc5-4ae1-9e3c-19f9fc9bbf86",
        "Amount": 1
    },
    {
        "ItemId": "e5276289-f839-4bde-acce-309ea7959e45",
        "Amount": 1
    }
  ],
  "DeleteEmptyStacks": true,
  "StoreId": "f116f1d4-64f9-4be7-9660-a3c1f021100b"
}

下一个片段是成功 API 调用后的预期返回。

{
    "code": 200,
    "status": "OK",
    "data": {
        "ETag": "1/MjEz",
        "IdempotencyId": "d710508f-defc-4382-bbd1-a3576417b3f7",
        "TransactionIds": [
            "212",
            "213"
        ]
    }
}

你会注意到在响应中，你会得到 2 个不同的 TransactionIds。这是因为 DeleteEmptyStacks 属性被作为额外的交易处理。在前面的示例中，交易 212 对应于捆绑包的购买，交易 213 对应于空 Cream 堆栈的删除（假设你的库存中只有 1 个 Cream）。

C# SDK

就 C# 代码应该是什么样子而言，下面你可能会找到我们示例的一个片段。

var purchaseRequest = new PurchaseInventoryItemsRequest
{
    Entity = new PlayFab.EconomyModels.EntityKey { Id = entityKey.Id, Type = entityKey.Type },
    Item = new InventoryItemReference { Id = "34167d9f-c8d7-4e17-9a87-b6af1fc389b2" }, //bundle id
    Amount = 1,
    PriceAmounts = new List<PurchasePriceAmount>() { 
        new PurchasePriceAmount { 
            ItemId = "e5276289-f839-4bde-acce-309ea7959e45", 
            Amount = 1 
        }, //cream id and quantity
        new PurchasePriceAmount { 
            ItemId =  "0d2ab329-2fc5-4ae1-9e3c-19f9fc9bbf86", 
            Amount = 1 
        } //icebox id and quantity
    }, 
    StoreId = "f116f1d4-64f9-4be7-9660-a3c1f021100b",
    DeleteEmptyStacks = true
};

var result = await PlayFabEconomyAPI.PurchaseInventoryItemsAsync(purchaseRequest);

XBOX Services

PlayFab

制作游戏第 3 部分 - 编码

第 3 部分 - 编码 + 示例

先决条件

步骤 1 - 配置环境设置

步骤 2 - 进行身份验证

C# SDK

API

C# SDK

API

步骤 3 - 设置你的起始库存

C# SDK

API

步骤 4 - 创建捆绑包

步骤 5 - 创建商店

步骤 6 - 向商店添加捆绑包

步骤 7 - 购买捆绑包

API

C# SDK

另请参阅

​第 3 部分 - 编码 + 示例

​先决条件

​步骤 1 - 配置环境设置

​步骤 2 - 进行身份验证

​C# SDK

​API

​C# SDK

​API

​步骤 3 - 设置你的起始库存

​C# SDK

​API

​步骤 4 - 创建捆绑包

​步骤 5 - 创建商店

​步骤 6 - 向商店添加捆绑包

​步骤 7 - 购买捆绑包

​API

​C# SDK

​另请参阅

第 3 部分 - 编码 + 示例

先决条件

步骤 1 - 配置环境设置

步骤 2 - 进行身份验证

C# SDK

API

C# SDK

API

步骤 3 - 设置你的起始库存

C# SDK

API

步骤 4 - 创建捆绑包

步骤 5 - 创建商店

步骤 6 - 向商店添加捆绑包

步骤 7 - 购买捆绑包

API

C# SDK

另请参阅