クイックスタート: JavaScript 用の PlayFab クライアントライブラリ

[アーティクル]
07/13/2023

JavaScript 用の PlayFab クライアントライブラリを開始して、プレーヤーを認証します。パッケージをインストールして、基本的なタスクのコード例を試します。

前提条件

PlayFab 開発者アカウント。タイトルの作成と TitleId の検索の詳細については、「ゲームマネージャーのクイックスタート」を参照してください。

クイックスタートガイドは、Web ブラウザーを実行できるオペレーティングシステムで動作します。

JavaScript プロジェクトのセットアップ

PlayFab API を呼び出すには、PlayFab 開発者アカウントが必要です。タイトルの作成と TitleId の検索の詳細については、「ゲームマネージャーのクイックスタート」を参照してください。

OS: このガイドは、Web ブラウザーを実行できるすべての OS で動作します。

新しいプロジェクトを設定するには、2 つの空のテキストファイルを含む新しいフォルダーを作成します。

PlayFabGettingStarted.html
PlayFabGettingStarted.js

PlayFab のインストールが完了しました。

コード例

このガイドでは、最初の PlayFab API 呼び出しを行う最小限の手順を示します。確認は Web ページに表示されます。パラメーターと戻り値の詳細については、最初に Postman テンプレートを使用することをお勧めします。

クライアントを認証する

お気に入りのテキストエディターで、次のように PlayFabGettingStarted.html の内容を更新します。

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

お気に入りのテキストエディターで、次のように PlayFabGettingStarted.js の内容を更新します。

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

この例で loginRequest オブジェクトの正しい形式を調べるには、LoginWithCustomID の API リファレンスをご覧ください。

コードを実行する

お気に入りのブラウザーで PlayFabGettingStarted.html を開きます。
[LoginWithCustomID の呼び出し] ボタンをクリックします。
結果のセクションに次のテキストが表示されます。"これで、最初の API 呼び出しが成功しました"

この時点で、他の api 呼び出しとゲームのビルドを開始できます。

利用可能なすべてのクライアント API 呼び出しの一覧については、PlayFab API リファレンスドキュメントをご覧ください。

コードを分解する

このセクションでは、コードの各部分について詳しく説明します。

HTML ファイルには、いくつかの重要な行があります。

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

この行は、PlayFab CDN からクライアント SDK を直接読み込みます。マイクロソフトの CDN には、常に PlayFabSDK の最新バージョンがホストされています。ファイルをダウンロードし、固定バージョンを使った方が安全性な可能性があります (PlayFab JavaScript SDK)

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

上記のように、 PlayFabGettingStarted.js には DoExampleLoginWithCustomID 関数が含まれています。これらの行は、Web ページに js ファイルをバインドし、そのスクリプトで DoExampleLoginWithCustomID 関数を呼び出します。他の項目は GUI にすぎません。

PlayFabClientSDK の関数は、対応する HTTP 要求の後に名前が付けられます。たとえば、LoginWithCustomID 関数に対応する HTTP リクエストにも "LoginWithCustomID" という名前をつけられます。リクエスト本文は、キーと値として JavaScript リクエストオブジェクトにパックされます。セッションチケットは、ログインから保存されるため、クライアント呼び出しには、要求ヘッダーのセッションチケットを含める必要はありません。

PlayFabGettingStarted.js の行単位のブレークダウン
- PlayFab.settings.titleId = "xxxx";
  - すべての PlayFab 開発者は、ゲームマネージャーでタイトルを作成します。ゲームを公開するとき、ゲームにそのタイトル ID をコードで記述する必要があります。これにより、クライアントは PlayFab 内で適切なデータにアクセスする方法を知ることができます。ほとんどのユーザーにとって、これは PlayFab が機能するための必須の手順です。
- var loginRequest = { TitleId: PlayFab.settings.titleId, CustomId: "GettingStartedGuide", CreateAccount: true };
  - ほとんどの PlayFab API メソッドには入力パラメーターが必要であり、それらの入力パラメーターは要求オブジェクトにパックされています
  - すべての API のメソッドには一意の要求オブジェクトが必要であり、オプションパラメーターおよび必須パラメーターが混在しています
    - LoginWithCustomID の場合、プレイヤーを一意に識別する CustomId と、この呼び出しで新しいアカウントを作成できるようにする CreateAccount の必須パラメーターがあります。 TitleId は、JavaScript の別の必須パラメーターであり、PlayFab.settings.titleId に一致する必要があります。
    - TitleIdの保存場所については、「ゲームマネージャーのクイックスタート」を参照してください。
- この場合、TitleId、customId、および CreateAccount は LoginWithCustomID の要求本文から作成されます。要求本文フィールドは、要求オブジェクトにキーおよび値として含まれます。要求ヘッダーのセッションチケットは、ログインから保存されるため、SessionTicket は要求オブジェクトには含まれません。
- PlayFabClientSDK.LoginWithCustomID(loginRequest, LoginCallback);
  - これにより、LoginWithCustomID への非同期要求が始まり、API 呼び出しが完了すると LoginCallback が呼び出されます。
  - ログイン時、ほとんどの開発者は適切なログイン方法を使うことを希望します。
    - すべてのログイン方法と入力パラメーターの一覧については、PlayFab ログインドキュメントをご覧ください。一般的な選択肢は次のとおりです。
- JavaScript を初めて使う場合は、開発者がコールバック関数について理解することをお勧めします。
- LoginCallback には result、error の 2 つのパラメーターがあります
  - 成功した場合、error は null になり、呼び出された API に従って、result オブジェクトに要求された情報が含められます。
  - この result には、プレイヤーに関するいくつかの基本的な情報が含まれていますが、ほとんどのユーザーの場合、ログインは他の API を呼び出す前の必須の手順です。
- error が null でない場合、API 呼び出しが失敗しました。

トラブルシューティング

API 呼び出しは多くの理由で失敗するため、必ずエラーの処理を試みる必要があります。
Error オブジェクトには、エラー名、エラーコード、およびエラーメッセージが含まれます。また、この情報はエラーを診断するのに十分なものです。
グローバル API メソッドのエラーコードは、PlayFab のグローバル API メソッドのエラーコードを参照してください。
API 呼び出しが失敗する理由 (可能性が高い順)
- PlayFabSettings.TitleId が設定されていない。 TitleId が設定されていない場合は、何も動作しません。
- 要求パラメーター。特定の API 呼び出しの正しい情報や必要な情報が指定されていない場合は失敗します。詳しくは、error.errorMessage, error.errorDetails または error.GenerateErrorReport() をご覧ください。
- デバイス接続の問題。携帯電話の接続が絶えず失われて再取得されるため、API 呼び出しが常にランダムに失敗し、その後すぐに機能する可能性があります。トンネルに入ると完全に切断される可能性があります。
PlayFab サーバーの問題。すべてのソフトウェアと同様、問題が生じる可能性があります。最新情報については、リリースノートをご覧ください。
- インターネットの信頼性は 100% ではありません。メッセージが破損したり、PlayFab サーバーに到達できないことがあります。
問題のデバッグで問題が発生し、エラー情報内の情報が不十分な場合、フォーラムをご覧ください。

次の手順

このクイックスタートでは、ユーザーを認証するための簡単な手順を示します。ユーザー認証の詳細については、「ログインの基本とベストプラクティス」を参照してください。

すばらしいコーディングになりますように。

クイックスタート: JavaScript 用の PlayFab クライアント ライブラリ