快速入门：iOS

项目
03/02/2024

开始使用适用于 iOS 的 PlayFab 服务 SDK。按照以下步骤将库包含在项目中，并尝试基本 PlayFab 功能的示例代码。

本快速入门可帮助你使用 iOS SDK 进行第一次 PlayFab API 调用。在继续操作之前，请确保已完成快速入门：Game Manager中的步骤，这可确保你拥有 PlayFab 帐户并熟悉 PlayFab Game Manager。

要求

PlayFab 开发人员帐户。
XCode IDE 已安装。

项目设置

从 PlayFab SDK 发布页将 PlayFab iOS SDK 下载到项目。

将 PlayFab C SDK 集成到你自己的项目中

向游戏添加二进制文件

通过下载或从源代码构建获得二进制文件后，就可以轻松地将其集成到游戏/应用程序中。需要将以下二进制文件添加到游戏中：

HttpClient_iOS.xcframework
PlayFabCore_iOS.xcframework
PlayFabServices_iOS.xcframework

按照以下说明添加它们：

在 XCode 中，导航到所需的目标并选择它。
在“常规”部分，向下滚动并在“框架、库和嵌入内容”部分中，选择“+”符号。
搜索 PlayFabServices / PlayFabCore / HttpClient 二进制文件，然后选择 xcframework 文件夹。（如果在 xcframework 文件夹中导航，也可以选择某特定库，但建议导入 xcframework 捆绑包，因为它适用于设备和模拟器版本。）
成功导入二进制文件后，HttpClient_iOS、PlayFabCore_iOS 和 PlayFabServices_iOS 会列在“框架”、“库”和“嵌入内容”下。

添加标头搜索路径

添加二进制文件后，需要确保标头搜索路径也已正确设置。

导航到项目。
选择“生成设置”，然后搜索“标头搜索路径”。
更新属性值以包括 SDK 标头。添加对 include 文件夹中的标头的引用。示例：
```
PlayFabCSdk-iOS/include
```

初始化和登录

请按照后续步骤操作，以使一些 PlayFab 示例调用能够正常工作。

标头

包括 PFServices.h 以访问所有包含的 PlayFab 功能。

#include <playfab/services/PFServices.h>

初始化

PlayFab 初始化需要两个函数调用： PFServicesInitialize 和 PFServiceConfigCreateHandle。此初始化的结果是 PFServiceConfigHandle。将此句柄提供给后续登录调用，将调用定向到 PlayFab 后端中的正确游戏。

    HRESULT hr = PFServicesInitialize(nullptr); // Add your own error handling when FAILED(hr) == true

    PFServiceConfigHandle serviceConfigHandle{ nullptr };

    hr = PFServiceConfigCreateHandle(
            "https://ABCDEF.playfabapi.com",    // PlayFab API endpoint - obtained in the Game Manager
            "ABCDEF",                           // PlayFab Title id - obtained in the Game Manager
            &serviceConfigHandle);

拥有 PFServiceConfigHandle后，可以使用它进行玩家登录呼叫。在 SDK 中，使用 PFAuthenticationLoginWith*Async 方法，如 PFAuthenticationLoginWithAppleAsync。此函数允许你使用 Apple 用户的标识令牌将玩家登录到 PlayFab。（请参阅 Apple 有关使用 Apple 登录对用户进行身份验证文档）。

进行登录调用后，可以使用 XAsyncGetStatus 检查调用的状态。状态以 E_PENDING 开始，并在调用成功完成后更改为 S_OK。如果由于某种原因调用失败，状态将反映该失败。对所有 PlayFab Services 调用的错误处理都以这种方式工作。

除了 S_OK 结果，还可返回 PFEntityHandle。使用此句柄作为登录玩家进行后续 PlayFab 调用。它包括以该玩家身份向 PlayFab 服务进行身份验证所需的任何材料。

PFAuthenticationLoginWithAppleRequest request{};
request.createAccount = true;
request.identityToken = identityToken; // A user identity token obtained from Apple

XAsyncBlock async{};
hr = PFAuthenticationLoginWithAppleAsync(serviceConfigHandle, &request, &async); // Add your own error handling when FAILED(hr) == true
hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage

std::vector<char> loginResultBuffer;
PFAuthenticationLoginResult const* loginResult;
size_t bufferSize;
hr = PFAuthenticationLoginWithAppleGetResultSize(&async, &bufferSize);
loginResultBuffer.resize(bufferSize);

PFEntityHandle entityHandle{ nullptr };
hr = PFAuthenticationLoginWithAppleGetResult(&async, &entityHandle, loginResultBuffer.size(), loginResultBuffer.data(), &loginResult, nullptr);

服务调用

登录玩家后，现在可以调用 PlayFab 后端。下面是调用以获取当前玩家的 PlayFab 中存储的文件的示例。

获取 EntityKey

对 PlayFab 的某些调用有用的一点是了解玩家的 PFEntityKey。拥有 PFEntityToken后，可以使用 PFEntityGetEntityKey 检索 PFEntityKey。

    PFEntityKey const* pEntityKey{};
    std::vector<char> entityKeyBuffer;
    size_t size{};
    HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size); // Add your own error handling when FAILED(hr) == true

    entityKeyBuffer.resize(size);
    hr = PFEntityGetEntityKey(entityHandle, entityKeyBuffer.size(), entityKeyBuffer.data(), &pEntityKey, nullptr);

调用 GetFiles

所有 PlayFab 调用都遵循类似的模式，即准备请求对象、进行调用（使用 PFEntityHandle 从登录名）、创建对象以接收响应，然后调用 GetResult 函数来填充新创建的容器。

    XAsyncBlock async{};
    PFDataGetFilesRequest requestFiles{};
    requestFiles.entity = pEntityKey;

    HRESULT hr = PFDataGetFilesAsync(entityHandle, &requestFiles, &async); // Add your own error handling when FAILED(hr) == true
    hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage

    size_t resultSize;
    hr = PFDataGetFilesGetResultSize(&async, &resultSize);

    std::vector<char> getFilesResultBuffer(resultSize);
    PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
    hr = PFDataGetFilesGetResult(&async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);

清理

当游戏已准备好关闭或需要出于其他某种原因清理 PlayFab 时，请确保关闭所有打开的句柄并调用 PFServicesUninitializeAsync。

    PFEntityCloseHandle(entityHandle);
    entityHandle = nullptr;

    PFServiceConfigCloseHandle(serviceConfigHandle);
    serviceConfigHandle = nullptr;

    XAsyncBlock async{};
    HRESULT hr = PFServicesUninitializeAsync(&async); // Add your own error handling when FAILED(hr) == true
    hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage

异步 API 模式

PlayFab 服务 SDK 遵循 GDK 中实现的异步编程模型。此编程模型涉及使用由 XAsync 库提供的任务和任务队列。此模型与其他 GDK 函数和扩展（如 Xbox 服务 API）一致。虽然它确实带来了一些复杂性，但也对异步操作具有高度的控制。

此示例演示如何对 PFDataGetFilesAsync进行异步调用。

    auto async = std::make_unique<XAsyncBlock>();
    async->callback = [](XAsyncBlock* async)
    {
        std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // take ownership of XAsyncBlock

        size_t resultSize;
        HRESULT hr = PFDataGetFilesGetResultSize(async, &resultSize);
        if (SUCCEEDED(hr))
        {
            std::vector<char> getFilesResultBuffer(resultSize);
            PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
            PFDataGetFilesGetResult(async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);
        }
    };

    PFDataGetFilesRequest requestFiles{};
    requestFiles.entity = m_pEntityKey;
    HRESULT hr = PFDataGetFilesAsync(m_entityHandle, &requestFiles, async.get());
    if (SUCCEEDED(hr))
    {
        async.release(); // at this point, the callback will be called so release the unique ptr
    }

错误处理

已完成 XAsync 操作返回 HTTP 状态代码。错误状态代码 HRESULT（例如调用 XAsyncGetStatus() 或 PF*Get() API 之一时的 HTTP_E_STATUS_NOT_FOUND）中显示为失败。

若要查看服务返回的详细错误消息，请参阅有关调试的下一部分。这些详细的错误消息在开发过程中非常有用，以便更好地了解 PlayFab 服务如何响应来自客户端的请求。

调试

在 PlayFab Services SDK 中查看结果和调试任何调用的最简单方法是启用调试跟踪。启用调试跟踪可让你在调试器输出窗口中查看结果，并将结果挂钩到游戏自己的日志中。

另请参阅

API 参考文档

通过