クイックスタート: Android

Android 向けの PlayFab Services SDK を始めましょう。次の手順に従って、ライブラリをプロジェクトに含め、基本的な PlayFab 機能のサンプルコードを試してください。このクイックスタートは、Android SDK を使用して最初の PlayFab API 呼び出しを行うのに役立ちます。続行する前に、クイックスタート: Game Manager の手順を完了し、PlayFab アカウントを持っており、PlayFab Game Manager に慣れていることを確認してください。

要件

PlayFab 開発者アカウント。
Android Studio がインストールされていること。

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

PlayFab SDK リリースページから PlayFab Android SDK をプロジェクトにダウンロードします。

PlayFab C SDK を独自のプロジェクトに統合する

以下の手順は、Android Studio を使用して新しいプロジェクトを作成したことを前提として書かれています。

バイナリをゲームに追加する

プロジェクトに統合する必要があるバイナリには 2 つの部分があります: 共有オブジェクトファイル (.so) と Android アーカイブファイル (.aar) です。バイナリを自分でビルドするか、リリースページからダウンロードできます。

.so ファイルの追加

これらのファイルは CMake を使用してプロジェクトに統合されます。

Android 用 PlayFab SDK リリースを解凍し、その内容を目的のディレクトリに配置します。
target_include_directories または同等の関数を使用して、PlayFab SDK リリースの “Include” 以下のヘッダーを追加します:

TARGET_INCLUDE_DIRECTORIES(
    ${PROJECT_NAME}
    "Include"
)

target_link_libraries または同等の関数を使用して、.so ファイルの場所をプロジェクトにリンクします。例:

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

.aar ファイルの追加

これらのファイルは Gradle を使用してプロジェクトに統合されます。

アプリレベルの Android プロジェクトディレクトリ内に libs フォルダーを作成します。プロジェクトディレクトリが現在どのようになっているかの例を次に示します:

.aar ファイルを libs フォルダーにコピーします。
libs フォルダーと同じディレクトリにあるアプリレベルの build.gradle ファイルの dependencies セクションに次の行を追加します。2 行目は libHttpClient の依存関係として必要です。

implementation fileTree(dir: 'libs', include: ['*.aar'])
implementation 'com.squareup.okhttp3:okhttp:4.9.1'

初期化とログイン

Android 用 PlayFab Services SDK を使用するようにプロジェクトが完全にセットアップされたので、次の手順に従っていくつかのサンプル呼び出しを動作させます。

初期セットアップ

まず、アプリケーションが Android の activity のインスタンスを持つようにセットアップする必要があります。また、NDK と JNI (Java Native Interface) を使用する小さな C/C++ アプリケーションもセットアップする必要があります。参考のための小さな例を次に示します: https://github.com/android/ndk-samples/tree/android-mk/hello-jni この例には、jstring を返すネイティブメソッドが含まれています:

jstring Java_com_example_hellojni_HelloJni_stringFromJNI(JNIEnv* env, jobject thiz)

ネイティブメソッドを使用して、PFServices の初期化に必要な 2 つのもの、つまり Java VM とアプリケーションコンテキストを取得できます。初期化のために同様のメソッドを作成できます:

void Java_com_example_hellojni_HelloJni_InitializeApp(JNIEnv* env, jobject appContext)

その後、JNIEnv 変数を使用して Java VM を取得できます。

    JavaVM* javaVM = nullptr;
    jint res = env->GetJavaVM(&javaVM);
    if (res != JNI_OK)
    {
        // error handling
    }

次に、jobject パラメーターでアプリケーションコンテキストを取得できます。

    applicationContext = env->NewGlobalRef(appContext);

これら 2 つの変数を保存したので、呼び出しを開始できます。

ヘッダー

含まれるすべての PlayFab 機能にアクセスするために PFServices.h をインクルードします:

#include <playfab/services/PFServices.h>

初期化

PlayFab の初期化には、PFServicesInitialize と PFServiceConfigCreateHandle の 2 つの関数呼び出しが必要です。この初期化の結果は PFServiceConfigHandle です。このハンドルを後続のログイン呼び出しに提供して、PlayFab バックエンドの正しいタイトルへの呼び出しを指示します。

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

PFServiceConfigHandle を取得したら、それを使用してプレイヤーのログイン呼び出しを行うことができます。SDK では、PFAuthenticationLoginWithCustomIDAsync のような PFAuthenticationLoginWith*Async メソッドを使用します。この関数を使用すると、カスタム ID を使用してプレイヤーを PlayFab にログインさせることができます。ログイン呼び出しを行った後、XAsyncGetStatus で呼び出しのステータスを確認できます。ステータスは E_PENDING から始まり、呼び出しが正常に完了すると S_OK に変わります。何らかの理由で呼び出しが失敗した場合、ステータスはその失敗を反映します。すべての PlayFab Services 呼び出しのエラー処理はこのように機能します。 S_OK の結果とともに、PFEntityHandle が返されます。このハンドルを使用して、ログインしたプレイヤーとして後続の PlayFab 呼び出しを行います。これには、そのプレイヤーとして PlayFab サービスで認証するために必要なあらゆるマテリアルが含まれています。

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

サービス呼び出し

プレイヤーをログインさせた後、PlayFab バックエンドへの呼び出しを行えます。現在のプレイヤーの PlayFab に保存されたファイルを取得する呼び出しの例を次に示します。

EntityKey の取得

PlayFab への一部の呼び出しに役立つのは、プレイヤーの PFEntityKey を知ることです。PFEntityToken を取得したら、PFEntityGetEntityKey で PFEntityKey を取得できます。

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

GetFiles の呼び出し

すべての PlayFab 呼び出しは、リクエストオブジェクトを準備し、呼び出しを行い (ログインからの PFEntityHandle を使用)、レスポンスを受け取るオブジェクトを作成し、次に GetResult 関数を呼び出して新しく作成されたコンテナーを埋めるという同様のパターンに従います。

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

クリーンアップ

ゲームをシャットダウンする準備ができたときや、その他の理由で PlayFab をクリーンアップする必要があるときは、開いているすべてのハンドルを閉じ、PFServicesUninitializeAsync を呼び出すようにします。

    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

非同期 API パターン

PlayFab Services SDK は、GDK で実装された非同期プログラミングモデルに従います。このプログラミングモデルには、XAsync ライブラリによって提供されるタスクとタスクキューの使用が含まれます。このモデルは、他の GDK 関数や拡張機能 (XBOX Services API など) と一貫しています。若干の複雑さは導入しますが、非同期操作に対する高度な制御ももたらします。この例は、PFDataGetFilesAsync への非同期呼び出しを行う方法を示しています。

    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
    }

エラー処理

完了した XAsync 操作は HTTP ステータスコードを返します。エラーステータスコードは、XAsyncGetStatus() または PF*Get() API のいずれかを呼び出すときに、HTTP_E_STATUS_NOT_FOUND のような失敗の HRESULT として現れます。サービスから返される詳細なエラーメッセージを確認するには、デバッグに関する次のセクションを参照してください。これらの詳細なエラーメッセージは、開発中に、PlayFab サービスがクライアントからのリクエストにどのように反応するかをよりよく理解するのに役立ちます。

デバッグ

PlayFab Services SDK の結果を確認し、任意の呼び出しをデバッグする最も簡単な方法は、デバッグトレースを有効にすることです。デバッグトレースを有効にすると、デバッガー出力ウィンドウで結果を確認し、結果をゲーム独自のログにフックすることができます。

リファレンス

API リファレンスドキュメント

​クイックスタート: Android

​要件

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

​PlayFab C SDK を独自のプロジェクトに統合する

​バイナリをゲームに追加する

​.so ファイルの追加

​.aar ファイルの追加

​初期化とログイン

​初期セットアップ

​ヘッダー

​初期化

​ログイン

​サービス呼び出し

​EntityKey の取得

​GetFiles の呼び出し

​クリーンアップ

​非同期 API パターン

​エラー処理

​デバッグ

​リファレンス