iOS 和 macOS 入门

项目
07/11/2023

本文档列出了将 PlayFab Party 集成到 iOS 或 macOS 应用程序中所需的基本先决条件和要求。完成平台特定步骤后，请参阅 PlayFab Party 快速入门以完成 PlayFab Party 入门。

先决条件

在开始本教程之前，确保已满足以下先决条件：

你已创建了一个 PlayFab 开发人员帐户
你已创建 PlayFab 游戏，并且您的游戏已为 PlayFab Party 允许列出
已安装 Xcode 版本 10.2.1 或更高版本
可以访问 PlayFab 群平台存储库
你已创建了一个 Apple 开发人员帐户，该帐户可用于对应用进行签名以进行部署。

注意：如果计划使用 XCode 模拟器进行测试，则需要将应用程序作为 64 位（$（ARCHS_STANDARD_64_BIT））体系结构的目标。目前不支持 32 位模拟器。

包括所需的库和标头文件

标头

需要包含 [PlayFab Party 分发存储库]（https://github.com/PlayFab/PlayFabParty/releases）中的以下头文件。

框架

需要将应用程序链接到 PlayFab Party 分发包中也存在的以下框架。
- iOS: PlayFabParty
- macOS: PlayFabPartyMac

注意

SSL 库是从 Open SSL 版本 XXX生成的。使用 XXX 或更高的 OpenSSL 版本

标头包括

群标头

除上面的 lib 文件和标头以外，还将需要 PlayFab SDK 的库和标头，以及应用所需的任何其他特定于平台的依赖项。有关详细信息，查看 iOS 示例的项目文件组织。

使 PlayFab Party 在 iOS 或 macOS 上正常工作的步骤

由于核心 Party 库是使用编写的 C++ ，因此可以直接从目标 C++ 代码访问它。为方便起见，我们创建了一个简单的 C++ Objective-wrapper 类来访问 Party lib 功能。在更高的层次上，你将需要一个有权访问群 API 方法的类来创建一个网络，并在网络中发送消息。在我们的 iOS 演示应用中，显示了 SimpleClientClass 作为示例。

//
//  SimpleClient.h
//  chatdemo_ios

#import <Foundation/Foundation.h>
#import "ChatEventHandler.h"

@interface SimpleClient : NSObject

@property (nonatomic) id<ChatEventHandler> chatEventHandler;

-(void) initialize;
-(void) setHandler:(id<ChatEventHandler>) messageHandler;
-(void) signInLocalUser;

-(void) createNetwork:(NSString*) networkId;
-(void) joinNetwork:(NSString*) networkId;
-(void) leaveNetwork;

-(void) sendTextAsVoice:(NSString*) text;
-(void) sendTextMessage:(NSString*) text;
-(void) setLanguageCode:(int) languageIndex;
-(NSArray *) getLanguageOptions;
-(int) getDefaultLanguageIndex;

-(NSString*) getSelectedUserName;

-(void) tick;

+(void) globalInitialize;
+(void) globalShutdown;

@end

上述对象桥由调用 C++ 到 NetworkManager.cpp 的纯实现文件提供支持，后者又调用 Party API。

下面是显示各个层的示例代码段：

SimpleClient Objective-C 接口公开了初始化 PlayFab Party 的方法。

// In SimpleClient.h
-(void) createNetwork:(NSString*) networkId;

SimpleClient 的实现还包括对对象的引用 C++ ，该对象通过网络管理器调用 Party API。

// In SimpleClient.mm

@interface SimpleClient ()

@end

@implementation SimpleClient

SimpleClientImpl* m_impl;

SimpleClientImpl 是一个 C++ 类，它执行创建 Party 网络的繁重工作，如下面的代码片段所示：

void
SimpleClientImpl::CreateNetwork(
    std::string &networkId
    )
{
    if (g_isRunning && g_initializeCompleted)
    {
        Managers::Get<NetworkManager>()->Initialize(c_pfTitleId);
        m_messageHandler->OnStartLoading();
        Managers::Get<NetworkManager>()->CreateAndConnectToNetwork(
            networkId.c_str(),
            [this, networkId](std::string message)
            {
                this->SendSysLogToUI("create network: %s", message.c_str());
                Managers::Get<PlayFabManager>()->SetDescriptor(
                    networkId,
                    message, 
                    [this, message](void)
                    {
                        m_messageHandler->OnEndLoading();
                        this->SendSysLogToUI("set network descriptor %s", "successed");
                        std::string l_message = message;
                        m_messageHandler->OnNetworkCreated(l_message);
                    });
            },
            [this](PartyError error)
            {
                m_messageHandler->OnEndLoading();
                this->SendSysLogToUI("create network failed: %s", GetErrorMessage(error));
            });
    }
}

在上面的代码片段中，SimpleClient 调用 NetworkManager：：CreateAndConnectToNetwork（），后者调用 Party.h 中公开的原始 Party API

void 
NetworkManager::CreateAndConnectToNetwork(
    const char *networkId, 
    std::function<void(std::string)> callback, 
    std::function<void(PartyError)> errorCallback
    )
{
    DEBUGLOG("NetworkManager::CreateAndConnectToNetwork()\n");

    PartyNetworkConfiguration cfg = {};

    // Setup the network to allow the maximum number of single-device players of any device type
    cfg.maxDeviceCount = c_maxNetworkConfigurationMaxDeviceCount;
    cfg.maxDevicesPerUserCount = 1;
    cfg.maxEndpointsPerDeviceCount = 1;
    cfg.maxUserCount = c_maxNetworkConfigurationMaxDeviceCount;
    cfg.maxUsersPerDeviceCount = 1;

    //Get the uid from the local chat control
    PartyString uid = nullptr;
    PartyError err = m_localUser->GetEntityId(&uid);

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("GetUserIdentifier failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return;
    }

    // Setup the network invitation configuration to use the network id as an invitation id and allow anyone to join.
    PartyInvitationConfiguration invitationConfiguration{
        networkId,                                  // invitation identifier
        PartyInvitationRevocability::Anyone,        // revokability
        0,                                          // authorized user count
        nullptr                                     // authorized user list
    };

    // Initialize an empty network descriptor to hold the result of the following call.
    PartyNetworkDescriptor networkDescriptor = {};

    // Create a new network descriptor
    err = PartyManager::GetSingleton().CreateNewNetwork(
        m_localUser,                                // Local User
        &cfg,                                       // Network Config
        0,                                          // Region List Count
        nullptr,                                    // Region List
        &invitationConfiguration,                   // Invitation configuration
        nullptr,                                    // Async Identifier
        &networkDescriptor,                         // OUT network descriptor
        nullptr                                     // applied initialinvitationidentifier.
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("CreateNewNetwork failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return;
    }

    // Connect to the new network
    if (InternalConnectToNetwork(networkDescriptor, networkId, errorCallback))
    {
        m_state = NetworkManagerState::WaitingForNetwork;
        m_onnetworkcreated = callback;
        m_onnetworkcreatederror = errorCallback;
        m_onnetworkconnectedError = errorCallback;
    }
}

同样，SimpleClient Objective-C 接口中的每个方法都通过 SimpleClientImpl 和 NetworkManager 映射到 Party API。

备注

如果 PlayFab Party 旨在用于语音聊天，则需要向应用程序授予麦克风访问权限。为此，请确保将以下属性添加到应用程序的 Info.plist 文件中。

<key>NSMicrophoneUsageDescription</key>
<string>The application requires access to the microphone for voice chat.</string>

后续步骤

完成平台特定步骤以将 Party 库集成到 iOS 或 macOS 应用程序后，请参阅 PlayFab Party 快速入门以完成 PlayFab Party 入门。

通过

iOS 和 macOS 入门

先决条件

包括所需的库和标头文件

标头

框架

使 PlayFab Party 在 iOS 或 macOS 上正常工作的步骤

备注

后续步骤

其他资源