クイックスタート: Android

[アーティクル]
03/06/2024

Android 用 PlayFab Services SDK を使用して開始します。次の手順に従ってプロジェクトにライブラリを含め、基本的な PlayFab 機能のサンプルコードを試します。

このクイックスタートでは、Android SDK を使用して最初の PlayFab API 呼び出しを行います。続行する前に、PlayFab アカウントを作成して PlayFab ゲームマネージャーの使い方に慣れるため、必ず「クイックスタート: ゲームマネージャー」の手順を完了してください。

要件

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

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

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

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

ここに示す手順は、既に Android Studio を使用して新しいプロジェクトを作成済みであることを前提として記述されています。

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

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

.so ファイルの追加

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

PlayFab SDK for Android リリースを解凍し、その内容を目的のディレクトリに配置します。
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 フォルダーにコピーします。
アプリレベル build.gradle ファイル (libs フォルダーと同じディレクトリ内のファイル) の依存関係セクションに、これらの行を追加します。 2 行目は、libHttpClient 用の依存関係として必要です。

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

Init とログイン

Android 用 PlayFab Services SDK を使用するためのプロジェクトセットアップが完了したので、次に、以下の手順に従って、いくつかのサンプル呼び出しが機能するようにします。

初期セットアップ

まず、アプリケーションをセットアップして Android アクティビティのインスタンスを作成する必要があります。また、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)

Java VM とアプリケーションコンテキストは、ネイティブメソッドを使用して取得できます。これら 2 つの要素は PFServices を初期化するために必要です。次のように、初期化を目的とした同様のメソッドを作成することもできます。

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 で、PFAuthenticationLoginWith*Async メソッド (例: PFAuthenticationLoginWithCustomIDAsync) を使用します。この関数を使用すると、カスタム 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 の一部の呼び出しに役立つことの 1 つは、プレーヤーの 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 ファイルの追加

Init とログイン

初期セットアップ

ヘッダー

初期化

ログイン

サービス呼び出し

EntityKey の取得

GetFiles の呼び出し

クリーンアップ

非同期 API パターン

エラー処理

デバッグ

リファレンス

フィードバック

その他のリソース

次の方法で共有

クイック スタート: Android

要件

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

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

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

.so ファイルの追加

.aar ファイルの追加

Init とログイン

初期セットアップ

ヘッダー

初期化

ログイン

サービス呼び出し

EntityKey の取得

GetFiles の呼び出し

クリーンアップ

非同期 API パターン

エラー処理

デバッグ

リファレンス

フィードバック

その他のリソース

クイックスタート: Android