Schnellstart: Android
Erste Schritte mit dem PlayFab Services SDK für Android. 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 Android 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.
- Android Studio ist installiert.
Projekteinrichtung
Laden Sie das PlayFab Android SDK von der Releaseseite des PlayFab SDK in Ihr Projekt herunter.
Integrieren des PlayFab C SDK in Ihr eigenes Projekt
Diese nächsten Schritte werden unter der Annahme geschrieben, dass Sie ein neues Projekt mit Android Studio erstellt haben.
Hinzufügen von Binärdateien zu Ihrem Spiel
Es gibt zwei Teile der Binärdateien, die Sie in Ihr Projekt integrieren müssen: die freigegebenen Objektdateien (.so) und die Android-Archivdateien (.aar). Sie können die Binärdateien selbst erstellen oder von der Releaseseite herunterladen.
Hinzufügen der SO-Dateien
Diese Dateien werden mithilfe von CMake in Ihr Projekt integriert.
Entzippen Sie das PlayFab SDK für Android-Release, und platzieren Sie den Inhalt im gewünschten Verzeichnis.
Fügen Sie mit target_include_directories oder einer anderen entsprechenden Funktion die Header unter "Include" aus der PlayFab SDK-Version hinzu:
TARGET_INCLUDE_DIRECTORIES(
${PROJECT_NAME}
"Include"
)
Verknüpfen Sie mit target_link_libraries oder einer anderen entsprechenden Funktion die Speicherorte der SO-Dateien mit Ihrem Projekt.
Beispiel:
set(PLAYFAB_SERVICES_PATH "[LOCATION OF YOUR FILE]/libPlayFabServices.Android.so")
set(PLAYFAB_CORE_PATH "[LOCATION OF YOUR FILE]/libPlayFabCore.Android.so")
set(LIBHTTPCLIENT_PATH "[LOCATION OF YOUR FILE]/libHttpClient.Android.so")
TARGET_LINK_LIBRARIES(
[YOUR PROJECT NAME]
${PLAYFAB_SERVICES_PATH}
${PLAYFAB_CORE_PATH}
${LIBHTTPCLIENT_PATH}
)
Hinzufügen der AAR-Dateien
Diese Dateien werden mithilfe von Gradle in Ihr Projekt integriert.
- Erstellen Sie einen Ordner libs im Android-Projektverzeichnis auf App-Ebene. Hier sehen Sie ein Beispiel dafür, wie Ihr Projektverzeichnis jetzt aussehen sollte:
Kopieren Sie die AAR-Dateien in den Ordner libs.
Fügen Sie in der Datei build.gradle auf App-Ebene, die sich im gleichen Verzeichnis wie der Ordner libs befindet, diese Zeilen dem Abschnitt dependencies hinzu. Die zweite Zeile ist als Abhängigkeit für libHttpClient erforderlich.
implementation fileTree(dir: 'libs', include: ['*.aar'])
implementation 'com.squareup.okhttp3:okhttp:4.9.1'
Initialisieren und Anmelden
Nachdem Ihr Projekt nun vollständig für die Verwendung des PlayFab Services SDK für Android eingerichtet ist, führen Sie die nächsten Schritte aus, um einige Beispielaufrufe zum Funktionieren zu bringen.
Ersteinrichtung
Zunächst müssen Sie Ihre Anwendung so einrichten, dass sie über eine instance einer Android-Aktivität verfügt. Außerdem müssen Sie eine kleine C/C++-Anwendung einrichten, um das NDK mit JNI (Java Native Interface) zu verwenden. Hier ist ein kleines Beispiel als Referenz: https://github.com/android/ndk-samples/tree/android-mk/hello-jni.
Das Beispiel enthält eine native Methode, die eine jstring zurückgibt:
jstring Java_com_example_hellojni_HelloJni_stringFromJNI(JNIEnv* env, jobject thiz)
Native Methoden können verwendet werden, um den virtuellen Java-Computer und den Anwendungskontext abzurufen. Dies sind zwei Dinge, die zum Initialisieren von PFServices erforderlich sind. Sie können eine ähnliche Methode für die Initialisierung erstellen:
void Java_com_example_hellojni_HelloJni_InitializeApp(JNIEnv* env, jobject appContext)
Die Java-VM kann dann mithilfe der JNIEnv-Variablen abgerufen werden.
JavaVM* javaVM = nullptr;
jint res = env->GetJavaVM(&javaVM);
if (res != JNI_OK)
{
// error handling
}
Als Nächstes kann der Anwendungskontext mit dem jobject-Parameter abgerufen werden.
applicationContext = env->NewGlobalRef(appContext);
Nachdem Sie diese beiden Variablen gespeichert haben, können wir damit beginnen, Aufrufe auszuführen.
Header
Fügen 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.
HCInitArgs initArgs;
// Use the Java VM and application context from earlier
initArgs.javaVM = javaVm;
initArgs.applicationContext = applicationContext;
HRESULT hr = PFServicesInitialize(nullptr, &initArgs); // 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);
Anmelden
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 PFAuthenticationLoginWithCustomIDAsync. Mit dieser Funktion können Sie sich mit einer benutzerdefinierten ID bei PlayFab anmelden.
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.
PFAuthenticationLoginWithCustomIDRequest request{};
request.createAccount = true;
request.customId = "player1";
XAsyncBlock async{};
HRESULT hr = PFAuthenticationLoginWithCustomIDAsync(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 = PFAuthenticationLoginWithCustomIDGetResultSize(&async, &bufferSize);
loginResultBuffer.resize(bufferSize);
PFEntityHandle entityHandle{ nullptr };
hr = PFAuthenticationLoginWithCustomIDGetResult(&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.