Schnellstart: PlayFab-Clientbibliothek für JavaScript

Artikel
07/11/2023

Erste Schritte mit der PlayFab-Clientbibliothek für JavaScript, um einen Spieler zu authentifizieren. Führen Sie die Schritte aus, um das Paket zu installieren und Beispielcode für grundlegende Aufgaben auszuprobieren.

Voraussetzungen

Ein PlayFab-Entwicklerkonto. Informationen zum Erstellen eines Titels und zum Suchen nach TitleId finden Sie unter Game Manager-Schnellstart.

Die Schnellstartanleitung funktioniert auf jedem Betriebssystem, auf dem ein Webbrowser ausgeführt werden kann.

JavaScript-Projekteinrichtung

Bevor Sie eine PlayFab-API aufrufen können, müssen Sie über ein PlayFab-Entwicklerkonto verfügen. Informationen zum Erstellen eines Titels und zum Suchen nach TitleId finden Sie unter Game Manager-Schnellstart.

Betriebssystem: Dieser Leitfaden funktioniert auf jedem Betriebssystem, auf dem ein Webbrowser ausgeführt werden kann.

Um ein neues Projekt einzurichten, erstellen Sie einen neuen Ordner mit zwei leeren Textdateien:

PlayFabGettingStarted.html
PlayFabGettingStarted.js

Das war's – PlayFab-Installation abgeschlossen!

Codebeispiele

Dieser Leitfaden enthält die Mindestschritte für ihren ersten PlayFab-API-Aufruf. Die Bestätigung ist auf der Webseite sichtbar. Für weitere Informationen zu Parametern und Rückgabewerten empfehlen wir zunächst die Verwendung der Postman-Vorlage .

Authentifizieren des Clients

Aktualisieren Sie in Ihrem bevorzugten Text-Editor den Inhalt von PlayFabGettingStarted.html wie folgt:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>PlayFab JavaScript Unit Tests</title>
    <script type="text/javascript" src="https://download.playfab.com/PlayFabClientApi.js"></script>
    <script type="text/javascript" src="PlayFabGettingStarted.js"></script>
</head>
<body>
    PlayFab Getting Started Guide<br />
    TitleID: <input type="text" id="titleId" value="144"><br />
    CustomID: <input type="text" id="customId" value="GettingStartedGuide"><br />
    <input type="button" value="Call LoginWithCustomID" onclick="DoExampleLoginWithCustomID()"><br />
    Result:<br />
    <textarea id="resultOutput" cols="60" rows="5"></textarea><br />
</body>
</html>

Aktualisieren Sie in Ihrem bevorzugten Text-Editor den Inhalt von PlayFabGettingStarted.js wie folgt:

function DoExampleLoginWithCustomID(){
    PlayFab.settings.titleId = document.getElementById("titleId").value;
    var loginRequest = {
        // Currently, you need to look up the required and optional keys for this object in the API reference for LoginWithCustomID. See the Request Headers and Request Body.
        TitleId: PlayFab.settings.titleId,
        CustomId: document.getElementById("customId").value,
        CreateAccount: true
    };

    PlayFabClientSDK.LoginWithCustomID(loginRequest, LoginCallback);
}

// callback functions take two parameters: result and error
// see callback functions in JavaScript if unclear
var LoginCallback = function (result, error) {
    if (result !== null) {
        document.getElementById("resultOutput").innerHTML = "Congratulations, you made your first successful API call!";
    } else if (error !== null) {
        document.getElementById("resultOutput").innerHTML =
            "Something went wrong with your first API call.\n" +
            "Here's some debug information:\n" +
            PlayFab.GenerateErrorReport(error);
    }
}

Informationen zum Suchen des richtigen Formats für das loginRequest-Objekt in diesem Beispiel finden Sie in der API-Referenz für LoginWithCustomID.

Ausführen des Codes

Öffnen Sie PlayFabGettingStarted.html in Ihrem bevorzugten Browser.
Klicken Sie auf die Schaltfläche LoginWithCustomID anrufen.
Im Abschnitt Ergebnis sollte der folgende Text angezeigt werden: "Herzlichen Glückwunsch, Sie haben Ihren ersten erfolgreichen API-Aufruf durchgeführt!"

An diesem Punkt können Sie damit beginnen, andere API-Aufrufe auszuführen und Ihr Spiel zu erstellen.

Eine Liste aller verfügbaren Client-API-Aufrufe finden Sie in der Dokumentation zu PlayFab-API-Verweisen .

Dekonstruieren des Codes

In diesem Abschnitt werden die einzelnen Teile des Codes ausführlich beschrieben.

Die HTML-Datei enthält einige wichtige Zeilen:

<script type="text/javascript" src="https://download.playfab.com/PlayFabClientApi.js"></script>

Diese Zeile lädt das Client-SDK direkt aus dem PlayFab CDN. Unser CDN hostet immer die neueste Version von PlayFabSDK. Es kann für Sie sicherer sein, die Dateien herunterzuladen und eine feste Version zu verwenden: PlayFab JavaScript SDK

<script type="text/javascript" src="PlayFabGettingStarted.js"></script>
...
<input type="button" value="Call LoginWithCustomID" onclick="DoExampleLoginWithCustomID()"><br />

Wie Sie oben sehen können, PlayFabGettingStarted.js enthält die DoExampleLoginWithCustomID -Funktion. Diese Zeilen binden die JS-Datei an unsere Webseite und rufen die DoExampleLoginWithCustomID Funktion in diesem Skript auf. Alles andere ist nur GUI.

Die Funktionen in PlayFabClientSDK werden nach den entsprechenden HTTP-Anforderungen benannt. Beispielsweise heißt die entsprechende HTTP-Anforderung für die LoginWithCustomID Funktion auch "LoginWithCustomID". Der Anforderungstext wird als Schlüssel und Werte in das JavaScript-Anforderungsobjekt gepackt. Das Sitzungsticket wird von der Anmeldung gespeichert, sodass Clientaufrufe nicht das Sitzungsticket aus dem Anforderungsheader enthalten müssen.

Zeilenaufschlüsselung für PlayFabGettingStarted.js
- PlayFab.settings.titleId = "xxxx";
  - Jeder PlayFab-Entwickler erstellt einen Titel in Game Manager. Wenn Sie Ihr Spiel veröffentlichen, müssen Sie diese titleId in Ihr Spiel codieren. Dadurch kann der Client wissen, wie auf die richtigen Daten in PlayFab zugegriffen werden kann. Für die meisten Benutzer ist es nur ein obligatorischer Schritt, der PlayFab funktioniert.
- var loginRequest = { TitleId: PlayFab.settings.titleId, CustomId: "GettingStartedGuide", CreateAccount: true };
  - Die meisten PlayFab-API-Methoden erfordern Eingabeparameter, und diese Eingabeparameter werden in ein Anforderungsobjekt gepackt.
  - Jede API-Methode erfordert ein eindeutiges Anforderungsobjekt mit einer Mischung aus optionalen und obligatorischen Parametern.
    - Für LoginWithCustomIDgibt es einen obligatorischen Parameter von , der CustomIdeinen Spieler eindeutig identifiziert, und CreateAccount, der die Erstellung eines neuen Kontos mit diesem Aufruf ermöglicht. TitleId ist ein weiterer obligatorischer Parameter in JavaScript und muss mit übereinstimmen PlayFab.settings.titleId.
    - Informationen dazu, wo Sie finden TitleId, finden Sie unter Game Manager-Schnellstart.
- In diesem Fall TitleIdstammen , customIdund CreateAccount aus dem Anforderungstext von LoginWithCustomID. Die Felder des Anforderungstexts sind als Schlüssel und Werte im Anforderungsobjekt enthalten. Das Sitzungsticket im Anforderungsheader wird von der Anmeldung gespeichert, sodass das SessionTicket nicht im Anforderungsobjekt enthalten ist.
- PlayFabClientSDK.LoginWithCustomID(loginRequest, LoginCallback);
  - Dadurch wird die asynchrone Anforderung an LoginWithCustomIDgestartet, die aufgerufen LoginCallback wird, wenn der API-Aufruf abgeschlossen ist.
  - Für die Anmeldung sollten die meisten Entwickler eine geeignetere Anmeldemethode verwenden.
    - Eine Liste aller Anmeldemethoden und Eingabeparameter finden Sie in der Dokumentation zur PlayFab-Anmeldung . Häufig sind folgende Optionen verfügbar:
- Wenn JavaScript noch nicht verwendet wird, empfehlen wir Entwicklern, sich mit Rückruffunktionen vertraut zu machen.
- LoginCallback enthält zwei Parameter: result, error
  - Bei erfolgreicher Ausführung ist der Fehler NULL, und das Ergebnisobjekt enthält die angeforderten Informationen gemäß der aufgerufenen API.
  - Dieses Ergebnis enthält einige grundlegende Informationen zum Spieler, aber für die meisten Benutzer ist die Anmeldung einfach ein obligatorischer Schritt vor dem Aufrufen anderer APIs.
- Wenn der Fehler nicht nulllautet, ist der API-Aufruf fehlgeschlagen.

Problembehandlung

API-Aufrufe können aus vielen Gründen fehlschlagen, und Sie sollten immer versuchen, Fehler zu behandeln.
Das Error-Objekt enthält den Fehlernamen, den Fehlercode und die Fehlermeldung. Zusammen sollten diese Informationen ausreichen, um Ihren Fehler zu diagnostizieren.
Fehlercodes für globale API-Methoden finden Sie unter Fehlercodes für globale API-Methoden von PlayFab.
Warum API-Aufrufe fehlschlagen (In der Reihenfolge der Wahrscheinlichkeit)
- PlayFabSettings.TitleId ist nicht festgelegt. Wenn TitleId nicht festgelegt ist, funktioniert nichts.
- Anforderungsparameter. Wenn Sie nicht die richtigen oder erforderlichen Informationen für einen bestimmten API-Aufruf angegeben haben, tritt ein Fehler auf. Weitere Informationen finden Sie unter error.errorMessage, error.errorDetails, oder error.GenerateErrorReport() .
- Gerätekonnektivitätsproblem. Mobiltelefone verlieren ständig die Konnektivität bzw. erhalten sie wieder, sodass jeder API-Aufruf zu einem beliebigen Zeitpunkt nach dem Zufallsprinzip fehlschlagen kann und dann sofort danach funktioniert. Wenn Sie in einen Tunnel gehen, können Sie vollständig getrennt werden.
PlayFab-Serverproblem. Wie bei der gesamten Software kann es Probleme geben. Informationen zu Updates finden Sie in unseren Versionshinweisen .
- Das Internet ist nicht 100% zuverlässig. Manchmal ist die Nachricht beschädigt oder kann den PlayFab-Server nicht erreichen.
Wenn Sie Probleme beim Debuggen eines Problems haben und die Informationen in den Fehlerinformationen nicht ausreichen, besuchen Sie uns bitte in unseren Foren.

Weitere Schritte

In dieser Schnellstartanleitung wird ein vereinfachtes Verfahren zum Authentifizieren eines Benutzers veranschaulicht. Weitere Informationen zur Benutzerauthentifizierung finden Sie unter Anmeldegrundlagen und bewährte Methoden.

Wir wünschen viel Vergnügen bei der Codeerstellung!