适用于本机和 Android Studio 的 Java 快速入门

项目
07/12/2023

本快速入门有助于启动并运行 PlayFab JavaSDK 和简单的 Java 程序。

您必须有 PlayFab 开发者帐户才能调用 PlayFab API。

本教程的目标是：

获取必要的 JAR 文件。
将 JAR 文件添加到 classpath。
创建执行自定义 ID 登录 API 调用的最小 Java 控制台应用程序。

获取必要的 JAR 文件

要使用 PlayFab JavaSDK，需要 PlayFab Client JavaSDK 及其依赖项 Google GSON。

在此处下载 PlayFab Client JavaSDK JAR 库。查找 client-sdk-*.jar 和相应的 Java Doc [可选但有用]。

您可以在此处下载最新的 Google GSON。查找 gson-*.jar。

使用 Intellij Idea 的项目设置

初始化简单的 Intellij Idea Java 项目后，请确保放置必要的 JAR 文件，如以下示例所示。

Intellij - 项目设置

下一步是将 JAR 文件添加到 classpath。导航到文件 ->，如下面的示例所示。

Intellij - 将 jar 文件添加到类路径

导航到库，然后添加一个新的 Java 库，如下图所示。

Intellij - 添加新的 Java 库

选择您添加到 libs 文件夹的 JAR 文件，然后选择确定，如下所示。

Intellij - 选择 jar 文件

如果要求 Module，则选择列表中的第一个。确保所有 JAR 文件均添加到库列表。

Intellij - 确保添加了 jar 文件

使用任何 IDE 的项目设置

主要要求是将 JAR 文件添加到 classpath。有关如何将 JAR 文件添加到 classpath 的信息，请参阅 IDE 指南。

设置您的首次 API 调用

使用下面显示的代码作为主类代码。

import java.util.concurrent.*;
import java.util.*;

import com.playfab.PlayFabErrors.*;
import com.playfab.PlayFabSettings;
import com.playfab.PlayFabClientModels;
import com.playfab.PlayFabClientAPI;

public class Main
{
    private static boolean _running = true;

    public static void main(String[] args) {
        PlayFabSettings.TitleId = "144";

        PlayFabClientModels.LoginWithCustomIDRequest request = new PlayFabClientModels.LoginWithCustomIDRequest();
        request.CustomId = "GettingStartedGuide";
        request.CreateAccount = true;

        FutureTask<PlayFabResult<com.playfab.PlayFabClientModels.LoginResult>> loginTask = PlayFabClientAPI.LoginWithCustomIDAsync(request);
        loginTask.run();

        while (_running) {
            if (loginTask.isDone()) { // You would probably want a more sophisticated way of tracking pending async API calls in a real game
                OnLoginComplete(loginTask);
            }

            // Presumably this would be your main game loop, doing other things
            try {
                Thread.sleep(1);
            } catch(Exception e) {
                System.out.println("Critical error in the example main loop: " + e);
            }
        }
    }

    private static void OnLoginComplete(FutureTask<PlayFabResult<com.playfab.PlayFabClientModels.LoginResult>> loginTask) {
        PlayFabResult<com.playfab.PlayFabClientModels.LoginResult> result = null;
        try {
            result = loginTask.get(); // Wait for the result from the async call
        } catch(Exception e) {
            System.out.println("Exception in PlayFab api call: " + e); // Did you assign your PlayFabSettings.TitleId correctly?
        }

        if (result != null && result.Result != null) {
            System.out.println("Congratulations, you made your first successful API call!");
        } else if (result != null && result.Error != null) {
            System.out.println("Something went wrong with your first API call.");
            System.out.println("Here's some debug information:");
            System.out.println(CompileErrorsFromResult(result));
        }

        _running = false; // Because this is just an example, successful login triggers the end of the program
    }

    // This is a utility function we haven't put into the core SDK yet. Feel free to use it.
    private static <RT> String CompileErrorsFromResult(PlayFabResult<RT> result) {
        if (result == null || result.Error == null)
            return null;

        String errorMessage = "";
        if (result.Error.errorMessage != null)
            errorMessage += result.Error.errorMessage;
        if (result.Error.errorDetails != null)
            for (Map.Entry<String, List<String>> pair : result.Error.errorDetails.entrySet() )
                for (String msg : pair.getValue())
                    errorMessage += "\n" + pair.getKey() + ": " + msg;
        return errorMessage;
    }
}

完成并执行

运行应用程序：

选择右上角的播放箭头>。这将启动程序执行，并且将显示输出面板。
查找 debug message。这表明 API 调用已成功。

Intellij - 运行程序

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

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

解析此代码

这个可选的最后一部分详细介绍了 GettingStarted.java 中的每一行。

导入语句
- 这是用于进行 PlayFab API 调用的最小导入集。
public static void main(String[] args) {
- 这只是一个开始 API 调用并等待它完成的基本循环。
- PlayFabSettings.TitleId = "xxxx";
  - 每个 PlayFab 开发者都在 Game Manager 中创建游戏。发布游戏时，必须将 titleId 编码到游戏中。这样客户端知道如何在 PlayFab 中访问正确数据。对于大多数用户而言，只需将其视为使 PlayFab 正常工作的必要步骤。
- PlayFabClientModels.LoginWithCustomIDRequest request = new PlayFabClientModels.LoginWithCustomIDRequest();
  - 大多数 PlayFab API 方法需要输入参数，而这些输入参数将打包到请求对象中。
  - 每个 API 方法都需要唯一请求对象，并且同时具有可选参数和强制参数。
    - 对于 LoginWithCustomIDRequest，存在唯一标识玩家的 CustomId 的强制参数，以及可利用此调用创建新帐户的 CreateAccount。
  - 对于登录，大多数开发者需要使用更合适的登录方法。
    - 有关所有登录方法的列表和输入参数，请参阅 PlayFab 登录文档。常用选项为：
      - LoginWithAndroidDeviceID
      - LoginWithIOSDeviceID
      - LoginWithEmailAddress
- FutureTask<PlayFabResult<com.playfab.PlayFabClientModels.LoginResult>> loginTask = PlayFabClientAPI.LoginWithCustomIDAsync(request);
  - 这将使用 Java FutureTask 框架开始对 LoginWithCustomID 的异步请求。
- 在（运行）时{ if (loginTask.isDone()) { OnLoginComplete(loginTask); } }
  - 运行一个不太重要的主循环，然后异步等待 loginTask 完成。
  - 完成后，调用 OnLoginComplete。
OnLoginComplete (loginTask)
- result = loginTask.get();
  - 获取异步结果（这不会导致阻止，因为我们确认 FutureTask 已经完成。
- 如果 (result.Result != null)，则表明 API 调用已成功。
  - 成功后，许多 API 回调的 result.Result 对象将包含所请求的信息。
  - LoginResult具体包含有关玩家的一些基本信息。但对于大多数用户而言，登录只是在调用其他 API 前的必要步骤。
- 如果 (result.Error != null)，则表明 API 调用失败。
  - API 调用可能由于多种原因而失败，您应始终尝试处理失败。
  - 为什么 API 调用失败（按可能性顺序）
    - 未设置 PlayFabSettings.TitleId。如果忘记将 TitleId 设置为游戏，则不会进行任何操作。
    - 请求参数。如果未为特定 API 调用提供正确或必需的信息，则调用将失败。有关详细信息，请参阅 error.errorMessage、error.errorDetails 或 error.GenerateErrorReport()。
    - 设备连接问题。手机不断失去/恢复连接，因此在任何时候任何 API 调用都可能随机失败，然后立即恢复运行。进入隧道将完全断开连接。
    - PlayFab 服务器问题。与所有软件一样，可能存在问题。有关更新，请参阅我们的发行说明。
    - 互联网并非 100% 可靠。有时消息已受损或无法到达 PlayFab 服务器。
- 如果在调试问题时遇到困难，并且错误信息中的信息不充分，请访问我们的论坛。

通过