iOS and macOS getting started

Article
06/27/2023

This document lists the basic prerequisites and requirements necessary to integrate PlayFab Party into your iOS or macOS applications. After completing the platform specific steps, see the Quickstart for PlayFab Party to finish getting started with PlayFab Party.

Prerequisites

Before you start this tutorial, ensure that the following prerequisites have been met:

You've created a PlayFab developer account
You've created a PlayFab Title and your title has been allow-listed for PlayFab Party
You have Xcode version 10.2.1 or higher installed
You have access to the PlayFab Party platforms repository
You've created an apple developer account that can be used to sign your app for deployment.

NOTE: If you're planning to use the XCode simulator for testing, you'll need to target your application for 64-bit ($(ARCHS_STANDARD_64_BIT)) architecture. 32-bit simulators are currently not supported.

Including the required libraries and header files

Headers

You'll need to include the following header files from the [PlayFab Party distribution repository] (https://github.com/PlayFab/PlayFabParty/releases).

Frameworks

You'll need to link your application against the following frameworks that are also found inside the PlayFab Party distribution packages.
- iOS: PlayFabParty
- macOS: PlayFabPartyMac

Note

The SSL libs are built from Open SSL version XXX. Use an OpenSSL version that is XXX or higher

Header includes

Party headers

In addition to the lib files and headers above, you'll also need the libs and headers for PlayFab SDK and any other platform-specific dependencies your app needs. Take a look at the project file organization for the iOS Sample for more info.

Steps to get PlayFab Party working on iOS or macOS

Since the core Party library is written using C++, it's directly accessible from objective C++ code. For convenience, we've made a simple Objective-C++ wrapper class to access the Party lib functionality. At a high level, you'll want a class that has access to Party API methods to create a network, connect to a network, and send messages across a network. The SimpleClientClass is shown as an example in our iOS demo app.

//
//  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

The above object bridge is backed by a pure C++ implementation file that calls into the NetworkManager.cpp , which in turn calls the Party APIs.

Here's an example snippet that shows the various layers:

The SimpleClient Objective-C interface exposes a method to initialize PlayFab Party.

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

The implementation of the SimpleClient also includes a reference to the C++ object that calls into Party APIs via the network manager.

// In SimpleClient.mm

@interface SimpleClient ()

@end

@implementation SimpleClient

SimpleClientImpl* m_impl;

The SimpleClientImpl is a C++ class that class that does the heavy lifting of creating the Party network as shown in the code snippet below:

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));
            });
    }
}

In the code snippet above, the SimpleClient calls into NetworkManager::CreateAndConnectToNetwork() which in turn calls the raw Party API exposed in Party.h

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;
    }
}

In a similar way, each method in the SimpleClient Objective-C interface is mapped to Party API via the SimpleClientImpl and NetworkManager.

Remarks

If PlayFab Party is intended to be used for voice chat, the application needs to be granted microphone access. To do this, ensure that the following property is added to the Info.plist file of the application.

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

Next steps

After completing the platform specific steps to integrate the Party library into your iOS or macOS application, refer to Quickstart for PlayFab Party to finish getting started with PlayFab Party.