Schnellstart: iOS
Erste Schritte mit dem PlayFab Services SDK für iOS. Führen Sie die folgenden Schritte aus, um die Bibliotheken in Ihr Projekt einzuschließen und den Beispielcode für die grundlegende PlayFab-Funktionalität auszuprobieren.
In dieser Schnellstartanleitung erfahren Sie, wie Sie Ihren ersten PlayFab-API-Aufruf mithilfe des iOS SDK ausführen. Bevor Sie fortfahren, stellen Sie sicher, dass Sie die Schritte unter Schnellstart: Game Manager ausgeführt haben, um sicherzustellen, dass Sie über ein PlayFab-Konto verfügen und mit dem PlayFab-Spiel-Manager vertraut sind.
Voraussetzungen
- Ein PlayFab-Entwicklerkonto.
- Xcode Installierte IDE.
Projekteinrichtung
Laden Sie das PlayFab iOS SDK von der Releaseseite des PlayFab SDK in Ihr Projekt herunter.
Integrieren des PlayFab C SDK in Ihr eigenes Projekt
Hinzufügen von Binärdateien zu Ihrem Spiel
Nachdem Sie Ihre Binärdateien durch Herunterladen oder Erstellen aus der Quelle erhalten haben, sollten Sie sie problemlos in Ihr Spiel/Ihre App integrieren können. Sie müssen ihrem Spiel die folgenden Binärdateien hinzufügen:
- HttpClient_iOS.xcframework
- PlayFabCore_iOS.xcframework
- PlayFabServices_iOS.xcframework
Befolgen Sie diese Anweisungen, um sie hinzuzufügen:
Navigieren Sie in XCode zum gewünschten Ziel, und wählen Sie es aus.
Scrollen Sie im Abschnitt Allgemein nach unten, und wählen Sie im Abschnitt "Frameworks, Bibliotheken und eingebettete Inhalte" das Zeichen "+" aus.
Suchen Sie nach Ihren PlayFabServices / PlayFabCore / HttpClient-Binärdateien , und wählen Sie die Ordner xcframework aus. (Sie können auch eine bestimmte Bibliothek auswählen, wenn Sie in den xcframework-Ordnern navigieren, aber das Importieren des xcframework-Bündels wird empfohlen, da es sowohl für Geräte- als auch für Simulatorbuilds funktioniert.)
Nach erfolgreichem Importieren der Binärdateien werden HttpClient_iOS, PlayFabCore_iOS und PlayFabServices_iOS unter Frameworks, Bibliotheken und eingebettete Inhalte aufgeführt.
Hinzufügen von Headersuchpfaden
Nachdem Binärdateien hinzugefügt wurden, müssen Sie sicherstellen, dass die Headersuchpfade ebenfalls ordnungsgemäß eingerichtet sind.
Navigieren Sie zu Ihrem Projekt.
Wählen Sie "Buildeinstellungen" aus, und suchen Sie dann nach "Headersuchpfade".
Aktualisieren Sie den Eigenschaftswert, um die SDK-Header einzuschließen. Fügen Sie einen Verweis auf die Header im Includeordner hinzu. Beispiel:
PlayFabCSdk-iOS/include
Initialisieren und Anmelden
Führen Sie die nächsten Schritte aus, damit einige PlayFab-Beispielaufrufe funktionieren.
Header
Schließen Sie PFServices.h ein, um Zugriff auf alle enthaltenen PlayFab-Funktionen zu erhalten.
#include <playfab/services/PFServices.h>
Initialisierung
Für die PlayFab-Initialisierung sind zwei Funktionsaufrufe erforderlich: PFServicesInitialize und PFServiceConfigCreateHandle. Das Ergebnis dieser Initialisierung ist pfServiceConfigHandle. Sie stellen dieses Handle für einen nachfolgenden Anmeldeaufruf bereit und leiten den Aufruf an den richtigen Titel im PlayFab-Back-End weiter.
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);
Anmeldung
Sobald Sie über eine PFServiceConfigHandle verfügen, können Sie es verwenden, um einen Spieleranmeldeanruf zu tätigen. Verwenden Sie im SDK eine PFAuthenticationLoginWith*Async-Methode wie PFAuthenticationLoginWithAppleAsync. Mit dieser Funktion können Sie sich mit dem Identitätstoken eines Apple-Benutzers bei PlayFab anmelden. (Weitere Informationen finden Sie in der Apple-Dokumentation zur Authentifizierung von Benutzern mit Anmeldung bei Apple).
Nach dem Tätigen eines Anmeldeaufrufs können Sie die status des Anrufs mit XAsyncGetStatus überprüfen. Die status beginnt als E_PENDING und ändert sich in S_OK, nachdem der Aufruf erfolgreich abgeschlossen wurde. Wenn der Aufruf aus irgendeinem Grund fehlschlägt, spiegelt die status diesen Fehler wider. Die Fehlerbehandlung bei allen PlayFab Services-Aufrufen funktioniert auf diese Weise.
Zusammen mit einem S_OK Ergebnis erhalten Sie ein PFEntityHandle zurück. Sie verwenden dieses Handle, um nachfolgende PlayFab-Aufrufe als angemeldeter Spieler zu tätigen. Es enthält alle Materialien, die für die Authentifizierung beim PlayFab-Dienst als betreffenden Spieler erforderlich sind.
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);
Dienstaufrufe
Nach der Anmeldung des Players können Sie jetzt Aufrufe an das PlayFab-Back-End senden. Hier sehen Sie ein Beispiel für einen Aufruf zum Abrufen von Dateien, die in PlayFab für den aktuellen Player gespeichert sind.
Abrufen des EntityKey
Eine Sache, die für einige Aufrufe an PlayFab nützlich sein kann, ist die Kenntnis des PFEntityKey des Spielers. Sobald Sie über ein PFEntityToken verfügen, können Sie einen PFEntityKey mit PFEntityGetEntityKey abrufen.
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);
Aufrufen von GetFiles
Alle PlayFab-Aufrufe folgen einem ähnlichen Muster: Vorbereiten des Anforderungsobjekts, Ausführen des Aufrufs (mit PFEntityHandle von login), Erstellen eines Objekts zum Empfangen der Antwort und aufrufen dann eine GetResult-Funktion , um den neu erstellten Container auszufüllen.
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);
Bereinigen
Wenn Ihr Spiel zum Herunterfahren bereit ist oder Sie PlayFab aus einem anderen Grund sauber müssen, stellen Sie sicher, dass Sie alle geöffneten Handles schließen und PFServicesUninitializeAsync aufrufen.
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
Asynchrones API-Muster
Das PlayFab Services SDK folgt dem im GDK implementierten asynchronen Programmiermodell . Dieses Programmiermodell umfasst die Verwendung von Aufgaben und Aufgabenwarteschlangen, die von der XAsync-Bibliothek bereitgestellt werden. Dieses Modell ist konsistent mit anderen GDK-Funktionen und -Erweiterungen (z. B. der Xbox Services-API). Dies führt zwar zu einer gewissen Komplexität, bietet aber auch ein hohes Maß an Kontrolle über asynchrone Vorgänge.
In diesem Beispiel wird gezeigt, wie Sie pfDataGetFilesAsync asynchron aufrufen.
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
}
Fehlerbehandlung
Abgeschlossene XAsync-Vorgänge geben HTTP-status-Codes zurück. Ein Fehler status Code manifestiert sich als Fehler-HRESULT, z. B. HTTP_E_STATUS_NOT_FOUND beim Aufrufen von XAsyncGetStatus() oder einer der PF*Get()-APIs.
Ausführliche Fehlermeldungen, die vom Dienst zurückgegeben werden, finden Sie im nächsten Abschnitt zum Debuggen. Diese detaillierten Fehlermeldungen können während der Entwicklung nützlich sein, um besser zu verstehen, wie der PlayFab-Dienst auf Anforderungen vom Client reagiert.
Debuggen
Die einfachste Möglichkeit, die Ergebnisse anzuzeigen und Aufrufe im PlayFab Services SDK zu debuggen, besteht darin, die Debugablaufverfolgung zu aktivieren. Wenn Sie die Debugablaufverfolgung aktivieren, können Sie sowohl die Ergebnisse im Ausgabefenster des Debuggers anzeigen als auch die Ergebnisse in die eigenen Protokolle Ihres Spiels einbinden.