> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS 和 macOS 快速入門

> PlayFab Party 的 iOS 和 macOS 整合需求，包括 Xcode 架構連結、麥克風權利和背景音訊設定。

本文件列出將 PlayFab Party 整合到 iOS 或 macOS 應用程式所需的基本先決條件和需求。完成平台專屬步驟之後，請參閱 [PlayFab Party 快速入門](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/networking/quickstart.md)，完成 PlayFab Party 的使用者入門。

## 先決條件

開始本教學課程之前，請確定已符合下列先決條件：

1. 您已建立 [PlayFab 開發人員帳戶](https://developer.playfab.com)
2. 您已建立 PlayFab 遊戲，且您的遊戲已加入 PlayFab Party 的允許清單
3. 您已安裝 Xcode 10.2.1 版或更新版本
4. 您可以存取 [PlayFab Party 平台存放庫](https://github.com/PlayFab/PlayFabParty)
5. 您已建立可用來簽署應用程式以進行部署的 Apple 開發人員帳戶。

注意：如果您打算使用 XCode 模擬器進行測試，需要將應用程式的目標設為 64 位元 (\$(ARCHS\_STANDARD\_64\_BIT)) 架構。目前不支援 32 位元模擬器。

## 包含必要的程式庫和標頭檔案

### 標頭

* 您需要包含來自 [PlayFab Party 發佈存放庫](https://github.com/PlayFab/PlayFabParty/releases)的下列標頭檔案。

### 架構

* 您需要將應用程式連結到下列架構，這些架構也位於 PlayFab Party 發佈套件中。
  * iOS: PlayFabParty
  * macOS: PlayFabPartyMac

> [!NOTE]
>
> SSL 程式庫是從 [Open SSL 版本 XXX](https://github.com/openssl/openssl/tree/OpenSSL_1_1_1-stable) 建置而成。請使用 XXX 或更新版本的 OpenSSL

標頭包含

[Party 標頭](https://github.com/PlayFab/PlayFabParty/tree/master/include)

除了上述 lib 檔案和標頭之外，您還需要 PlayFab SDK 的程式庫和標頭，以及應用程式所需的任何其他平台專屬相依性。如需詳細資訊，請參閱 iOS 範例的專案檔案組織。

## 讓 PlayFab Party 在 iOS 或 macOS 上運作的步驟

由於核心 Party 程式庫是以 C++ 撰寫，因此可以直接從 Objective-C++ 程式碼存取。為了方便起見，我們建立了一個簡單的 Objective-C++ 包裝函式類別來存取 Party 程式庫的功能。概括來說，您需要一個能存取 Party API 方法的類別，以建立網路、連線到網路，以及在網路上傳送訊息。我們的 iOS 示範應用程式以 [SimpleClientClass](https://github.com/PlayFab/PlayFabParty/blob/docs/iOS/PartySample/app/inc/SimpleClient.h) 作為範例。

```obj-c theme={null}
//
//  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](https://github.com/PlayFab/PlayFabParty/blob/docs/android/PartySampleNetworkCommon/lib/NetworkManager.cpp)，而後者再呼叫 Party API。

以下是顯示各個層級的範例程式碼片段：

SimpleClient Objective-C 介面公開了一個初始化 PlayFab Party 的方法。

```obj-c theme={null}
// In SimpleClient.h
-(void) createNetwork:(NSString*) networkId;
```

SimpleClient 的實作也包含 C++ 物件的參考，該物件會透過網路管理員呼叫 Party API。

```obj-c theme={null}
// In SimpleClient.mm

@interface SimpleClient ()

@end

@implementation SimpleClient

SimpleClientImpl* m_impl;
```

SimpleClientImpl 是一個 C++ 類別，負責建立 Party 網路的主要工作，如下列程式碼片段所示：

```cpp theme={null}
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](https://github.com/PlayFab/PlayFabParty/blob/docs/include/Party.h) 中公開的原始 Party API

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

    // Set the maximum number of devices allowed in a network to 16 devices
    constexpr uint8_t c_maxSampleNetworkDeviceCount = 16;
    static_assert(c_maxSampleNetworkDeviceCount <= c_maxNetworkConfigurationMaxDeviceCount, "Must be less than or equal to c_maxNetworkConfigurationMaxDeviceCount.");

    // Initialize network configuration for Party Network.
    PartyNetworkConfiguration cfg = {};
    cfg.maxDeviceCount = c_maxSampleNetworkDeviceCount;
    cfg.maxDevicesPerUserCount = 1;
    cfg.maxEndpointsPerDeviceCount = 1;
    cfg.maxUserCount = c_maxSampleNetworkDeviceCount;
    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 快速入門](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/networking/quickstart.md)，完成 PlayFab Party 的使用者入門。


## Related topics

- [大廳和配對 API 的即時訊息](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/networking/party-sdks/overview.md)
- [macOS 快速入門](https://docs.xbox.com/zh-TW/services/playfab/sdks/c/quickstart-macos.md)
- [iOS 快速入門](https://docs.xbox.com/zh-TW/services/playfab/sdks/c/quickstart-ios.md)
- [快速入門 (Windows) - Party 和 Multiplayer](https://docs.xbox.com/zh-TW/services/playfab/sdks/unified-sdk/quickstart-windows-party.md)
- [Party 快速入門](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/networking/quickstart.md)