快速入门：适用于 JavaScript 的 PlayFab 客户端库

项目
07/12/2023

开始使用适用于 JavaScript 的 PlayFab 客户端库对玩家进行身份验证。按照步骤安装程序包，并尝试使用基本任务的示例代码。

先决条件

PlayFab 开发人员帐户。有关创建游戏和查找 TitleId 的信息，请参阅游戏管理器快速入门。

快速入门指南适用于能够运行 Web 浏览器的任何操作系统。

JavaScript 项目设置

必须有 PlayFab 开发者帐户才能调用 PlayFab API。有关创建游戏和查找 TitleId 的信息，请参阅游戏管理器快速入门。

OS：本指南适用于能够运行 Web 浏览器的任何操作系统。

若要设置新项目，请创建包含两个空文本文件的新文件夹：

PlayFabGettingStarted.html
PlayFabGettingStarted.js

就这样 - PlayFab 安装完成！

代码示例

本指南提供进行首次 PlayFab API 调用的最小步骤。确认在网页上可见。有关参数和返回值的详细信息，建议先使用“Postman 模板”。

对客户端进行身份验证

在喜欢的文本编辑器中，更新以下 PlayFabGettingStarted.html 内容:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>PlayFab JavaScript Unit Tests</title>
    <script type="text/javascript" src="https://download.playfab.com/PlayFabClientApi.js"></script>
    <script type="text/javascript" src="PlayFabGettingStarted.js"></script>
</head>
<body>
    PlayFab Getting Started Guide<br />
    TitleID: <input type="text" id="titleId" value="144"><br />
    CustomID: <input type="text" id="customId" value="GettingStartedGuide"><br />
    <input type="button" value="Call LoginWithCustomID" onclick="DoExampleLoginWithCustomID()"><br />
    Result:<br />
    <textarea id="resultOutput" cols="60" rows="5"></textarea><br />
</body>
</html>

在喜欢的文本编辑器中，更新以下 PlayFabGettingStarted.js 内容:

function DoExampleLoginWithCustomID(){
    PlayFab.settings.titleId = document.getElementById("titleId").value;
    var loginRequest = {
        // Currently, you need to look up the required and optional keys for this object in the API reference for LoginWithCustomID. See the Request Headers and Request Body.
        TitleId: PlayFab.settings.titleId,
        CustomId: document.getElementById("customId").value,
        CreateAccount: true
    };

    PlayFabClientSDK.LoginWithCustomID(loginRequest, LoginCallback);
}

// callback functions take two parameters: result and error
// see callback functions in JavaScript if unclear
var LoginCallback = function (result, error) {
    if (result !== null) {
        document.getElementById("resultOutput").innerHTML = "Congratulations, you made your first successful API call!";
    } else if (error !== null) {
        document.getElementById("resultOutput").innerHTML =
            "Something went wrong with your first API call.\n" +
            "Here's some debug information:\n" +
            PlayFab.GenerateErrorReport(error);
    }
}

要查找该示例中 loginRequest 对象的正确格式，请参阅 LoginWithCustomID 的 API 参考。

运行代码

在喜欢的浏览器中打开 PlayFabGettingStarted.html。
单击 调用 LoginWithCustomID 按钮。
应在"结果"部分看到以下文本："恭喜，你已成功进行第一次 API 调用！"

此时，可以开始进行其他 API 调用并构建游戏。

有关所有可用客户端 API 调用的列表，请参阅 PlayFab API 参考文档。

解析此代码

本部分详细介绍代码的每个部分。

HTML 文件具有一些重要行：

<script type="text/javascript" src="https://download.playfab.com/PlayFabClientApi.js"></script>

此行直接从 PlayFab CDN 加载 Client-SDK。我们的 CDN 始终托管最新版本的 PlayFabSDK。对您而言，更安全的做法是下载这些文件，然后使用固定版本：PlayFab JavaScript SDK

<script type="text/javascript" src="PlayFabGettingStarted.js"></script>
...
<input type="button" value="Call LoginWithCustomID" onclick="DoExampleLoginWithCustomID()"><br />

如上所示， PlayFabGettingStarted.js 包含 DoExampleLoginWithCustomID 函数。这些行将 js 文件绑定到网页，并在该脚本中调用 DoExampleLoginWithCustomID 函数。其他一切都只是 GUI。

PlayFabClientSDK中的函数以相应的 HTTP 请求命名。例如，LoginWithCustomID 函数的相应 HTTP 请求也命名为“LoginWithCustomID”。请求正文以键和值的形式打包到 JavaScript 请求对象中。会话票证将从登录名中保存，因此客户端调用不需要合并请求标头中的会话票证。

PlayFabGettingStarted.js 的逐行分解
- PlayFab.settings.titleId = "xxxx";
  - 每个 PlayFab 开发者都在 Game Manager 中创建游戏。发布游戏时，必须将 titleId 编码到游戏中。这样客户端知道如何在 PlayFab 中访问正确数据。对于大多数用户而言，只需将其视为使 PlayFab 正常工作的必要步骤。
- var loginRequest = { TitleId: PlayFab.settings.titleId, CustomId: "GettingStartedGuide", CreateAccount: true };
  - 大多数 PlayFab API 方法需要输入参数，而这些输入参数已打包到请求对象中
  - 每个 API 方法都需要唯一请求对象，并且同时具有可选参数和强制参数
    - 对于 LoginWithCustomID，存在唯一标识玩家的 CustomId 的强制参数，以及可利用此调用创建新帐户的 CreateAccount。 TitleId 是 JavaScript 中的另一个强制参数，它必须与 PlayFab.settings.titleId 相匹配。
    - 若要了解在何处找到 TitleId，请参阅游戏管理器快速入门。
- 在这种情况下，TitleId、customId 和 CreateAccount 来自 LoginWithCustomID 的请求正文。请求正文字段作为键和值包含在请求对象中。请求标头中的会话票证将从登录名中保存，因此该 SessionTicket 不包含在请求对象中。
- PlayFabClientSDK.LoginWithCustomID(loginRequest, LoginCallback);
  - 这将开始对 LoginWithCustomID的异步请求，该请求将在 API 调用完成时调用 LoginCallback。
  - 对于登录，大多数开发者需要使用更合适的登录方法。
    - 有关所有登录方法和输入参数的列表，请参阅 PlayFab 登录文档。常用选项为：
- 如果不熟悉 JavaScript，建议开发人员阅读有关回调函数的信息。
- LoginCallback 包含两个参数：结果、错误
  - 成功时，error 将为 null，并且根据所调用的 API，result 对象将包含所请求的信息。
  - 此 result 包含有关玩家的一些基本信息，但对于大多数用户而言，登录只是在调用其他 API 之前的必要步骤。
- 如果未 null错误，则 API 调用失败。

故障排除

API 调用可能由于多种原因而失败，您应始终尝试处理失败。
错误对象包括错误名称、错误代码和错误消息。并且，此信息应足以诊断错误。
可在 PlayFab 的全局 API 方法错误代码中找到全局 API 方法错误代码。
为什么 API 调用失败（按可能性顺序）
- 未设置 PlayFabSettings.TitleId。如果未设置 TitleId，则没有任何功能。
- 请求参数。如果未为特定 API 调用提供正确或必要的信息，则调用将失败。有关详细信息，请参阅 error.errorMessage, error.errorDetails或 error.GenerateErrorReport()。
- 设备连接问题。手机不断失去/恢复连接，因此任何 API 调用在任何时候都可能随机失败，然后立即恢复运行。进入隧道将完全断开连接。
PlayFab 服务器问题。与所有软件一样，可能存在问题。有关更新，请参阅我们的发行说明。
- 互联网并非 100% 可靠。有时消息已受损或无法到达 PlayFab 服务器。
如果在调试问题时遇到困难，并且错误信息中的信息不充分，请访问我们的论坛。

后续步骤

此快速入门显示验证用户的简化过程。有关用户身份验证的其他信息，请参阅登录基础知识和最佳做法。

编码愉快！

通过