Android で EOS SDK を使用する

Android Studio を使用して Android プロジェクトで EOS SDK を実装する方法を説明します。

この操作ガイドは、Android StudioEpic Online Services (EOS) SDK を追加する方法、ビルド システムに確実に SDK を認識させる方法、および SDK を Android 向けに初期化する方法を説明します。

Android で SDK を実装する前に、プラットフォーム実装のための 一般的なガイドラインとリファレンス を再度ご確認ください

1. 必要なセットアップ

この操作ガイドは、Android NDK を使用して C/C++ コードをビルドできる Android Studio プロジェクトがすでに存在することを前提としています。まだプロジェクトの設定をしていない場合は、ガイド (https://developer.android.com/ndk/guides) に従って設定してください。また、このガイドでは、プロジェクトのビルドに Gradle を使用することを想定しています。その他のビルド ツールでも機能しますが、公式なサポートはされていません。

EOS SDK ではご使用のアプリケーションで libc++_shared をバンドルする必要があります。 Standard Template Library (STL) を使用する場合、.apk または .aab でバンドルする方法は developer.android.com/ndk/guides/cpp-support#selecting_a_c_runtime を参照してください。

異なる STL を使用している場合でも、NDK リリースのために関連づけられた libc++_shared ライブラリが必要となります。sources\cxx-stl\llvm-libc++\libs{arch}\ndk フォルダに .so ファイルがあります。これらはビルド ツールを使って最終ビルドでインクルードする必要があります。

2. EOS SDK を Android Studio プロジェクトへ追加する

Developer Portal から SDK をダウンロードすると、以下のアーティファクトを含む zip ファイルが提供されます。

  • EOS SDK から公開されたすべてのヘッダが含まれる include フォルダ。

  • アプリケーションのビルド時に使用することができる arm64-v8aarmeabi-v7a 用にビルドされた EOS SDK .so ファイルが含まれる lib フォルダ。

  • 正しいライブラリとアプリケーションを自動的にバンドルし、要求される許可と付随する java コードをプロジェクトに追加する EOSSDK.aar ファイル。

使用するビルド システムに関係なく、モジュールとして EOSSDK.aar をプロジェクトに作る必要があります。以下の手順に従って行います。

  1. [File]->[New]->[New Module…] をクリックします。

    Select New Module in the File menu

  2. オプションのリストから [Import .JAR/.AAR Package (.JAR/.AAR パッケージをインポート)] を選択して [Next (次へ)] を選択します。

    Select Import .JAR/.AAR Package

  3. 展開した zip ファイルから .aar ファイルを選択します。サブプロジェクト名 が自動的に「EOSSDK」と入力されます。そうならない場合は、手入力するか、別の名前を選択します。「EOSSDK」はプロジェクト内にインポートされたモジュールとして表示されます。

  4. EOSSDK フォルダに置かれているアプリケーションの build.gradle ファイルを開きます。

    EOSSDK appears in the project with the build.gradle file.

  5. 依存関係ブロックに実装 androidx.security:security-crypto:1.0.0-rc01 と実装プロジェクト (path: :EOSSDK) を追加します。

    dependencies {
        implementation 'androidx.appcompat:appcompat:1.1.0'
        implementation 'androidx.constraintlayout:constraintlayout:1.1.3'
        implementation 'androidx.security:security-crypto:1.0.0-rc01'
        implementation project(':EOSSDK')
    }

これにより SDK がプロジェクトにインポートされ、ビルド内にインクルードされました。aar ファイルにより、ビルド プロセス中に正しい .so ファイルが .apk/.aab に自動的に作成されます。

SDK 内に C ライブラリを直接統合する方法を次のセクションで説明します。

3. SDK をビルド システムと統合する

CMake または ndk-build を使って EOS SDK をプロジェクトに追加することができます。CMakendk-build は共に公式にサポートされた NDK との併用が可能なビルド システムです。このセクションでは、これらのシステムを使ってプロジェクトに SDK を使用する方法を説明します。

EOS With CMake を使用する

プロジェクトで CMake を使用している場合、プロジェクト内に「CMakeLists.txt」ファイルがあります。EOS SDK を NDK プロジェクトに作成するためには、CMake にライブラリの場所を伝える必要があります。

CMakeLists.txt

add_library(EOSSDK SHARED IMPORTED)

set(EOSSDKDIR PUT_PATH_TO_EXPANDED_ZIP_HERE)

set_property(TARGET EOSSDK PROPERTY IMPORTED_LOCATION ${EOSSDKDIR}/lib/${ANDROID_ABI}/libEOSSDK.so)
set_property(TARGET EOSSDK PROPERTY INTERFACE_INCLUDE_DIRECTORIES ${EOSSDKDIR}/include/)

CMakeLists.txt と同じディレクトリに zip を展開する場合は、このようになります。

CMakeLists.txt

add_library(EOSSDK SHARED IMPORTED)

set(EOSSDKDIR ${CMAKE_SOURCE_DIR})

set_property(TARGET EOSSDK PROPERTY IMPORTED_LOCATION ${EOSSDKDIR}/lib/${ANDROID_ABI}/libEOSSDK.so)
set_property(TARGET EOSSDK PROPERTY INTERFACE_INCLUDE_DIRECTORIES ${EOSSDKDIR}/include/)

最後に、EOS SDK がプロジェクトで適切なライブラリとリンクしているか確認します。Android Studio において C++ プロジェクトが 新規プロジェクト ウィザード で作成されます。以下のようになります。

CMakeLists.txt

target_link_libraries( # Specifies the target library.
                      native-lib
                      #Links the target library to the EOSSDK
                       EOSSDK

                      # Links the target library to the log library
                      # included in the NDK.
                      ${log-lib} )

ここで gradle を同期すると、EOS SDK 記号を C++ プロジェクトにインポート可能になります。Android-Specific Initialize Options セクションへ進みます。

CMake の使用方法については、https://developer.android.com/ndk/guides/cmake を参照してください。

EOS With ndk-build を使用する

プロジェクトに ndk-build を使用する場合、EOS SDK をモジュールとして「Android.mk」ビルドファイルに追加する必要があります。基本的な Android.mk ファイルは以下のようになります。

Android.mk

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

LOCAL_MODULE    := hello-jni
LOCAL_SRC_FILES := hello-jni.c
LOCAL_LDLIBS    := -llog -landroid

include $(BUILD_SHARED_LIBRARY)

このファイルは単一の .c ファイルで hello-jni モジュールをソースとして定義します。例えば以下のように、このファイルに同じモジュールを EOS SDK 用に定義する必要があります。

Android.mk

include $(CLEAR_VARS)
LOCAL_MODULE := eossdk
LOCAL_SRC_FILES := $(LOCAL_PATH)/lib/$(TARGET_ARCH_ABI)/libEOSSDK.so
LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include
include $(PREBUILT_SHARED_LIBRARY)

この例では、zip ファイルは「Android.mk」ファイルと同じフォルダに inflate されました。別の場所にファイルを指定するには、LOCAL_PATH を正しいパスに置き換えます。

hello-jni モジュールから EOS SDK モジュールを使用するにはこれらをリンクさせる必要があります。そのためには LOCAL_SHARED_LIBRARIES エントリとして sdk を追加します。さらに、c++_shared も参照されていることを確認する必要があります。

Android.mk

include $(CLEAR_VARS)
LOCAL_MODULE    := hello-jni
LOCAL_SRC_FILES := hello-jni.c
LOCAL_SHARED_LIBRARIES := eossdk c++_shared
LOCAL_LDLIBS    := -llog -landroid
include $(BUILD_SHARED_LIBRARY)

hello-jni モジュールは EOS SDK からエクスポートされたシンボルにアクセスできるようになりました。

フル デモの Android.mk ファイルは以下になります。特定のユースケースに対して変更する必要があります。

Android.mk

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)
LOCAL_MODULE := eossdk
LOCAL_SRC_FILES := $(LOCAL_PATH)/lib/$(TARGET_ARCH_ABI)/libEOSSDK.so
LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include
include $(PREBUILT_SHARED_LIBRARY)

include $(CLEAR_VARS)
LOCAL_MODULE    := hello-jni
LOCAL_SRC_FILES := hello-jni.c
LOCAL_SHARED_LIBRARIES := eossdk c++_shared
LOCAL_LDLIBS    := -llog -landroid
include $(BUILD_SHARED_LIBRARY)

ndk-build の詳細に関しては、https://developer.android.com/ndk/guides/ndk-build を参照してください。

4. Android 向けシステムの初期化オプション

EOS SDK が機能するには、 System.loadLibrary を使用してネイティブ ライブラリをロードする必要があります (一部のゲーム エンジンでは、プラグインのインポート時に自動的に実行されます)。

static {
    System.loadLibrary("EOSSDK");
}

アプリケーション コンテキストを次のように SDK に渡す必要があります。

EOSSDK.init(getApplicationContext());

ログインの例では、MainActivity クラスの onCreate でこれを行います。

Android で EOS SDK を初期化する次の例は、特定のユースケースで使用することができます。

extern "C" JNIEXPORT jstring JNICALL
Java_com_example_eossdk_Documentation_initializeSdk( JNIEnv* env,
jobject /* this */)
{
EOS_InitializeOptions SDKOptions = { 0 };
SDKOptions.ApiVersion = EOS_INITIALIZE_API_LATEST;
SDKOptions.ProductName = "EOSDocumentationExample";
SDKOptions.ProductVersion = "0.1";
EOS_EResult InitResult = EOS_Initialize(&SDKOptions);
if(InitResult != EOS_EResult::EOS_Success){
    return env->NewStringUTF("Error when initializing");
return env->NewStringUTF("Initialized successfully");
}

ディスク アクセスのためにオプションのディレクトリ パスを設定するために、EOS SDK にはプラットフォーム別の Android 用 システム初期化オプション があります。

extern "C" JNIEXPORT bool JNICALL
Java_com_epicgames_mobile_login_MainActivity_InitializeSDK(
        JNIEnv* env,
        jobject /* this */,
        jstring internalPath, jstring externalPath)
{
    EOS_InitializeOptions SDKOptions = { 0 };
    SDKOptions.ApiVersion = EOS_INITIALIZE_API_LATEST;
    SDKOptions.ProductName = "EOSDocumentationExample";
    SDKOptions.ProductVersion = "0.1";
    const char* androidInternalPath = env->GetStringUTFChars(internalPath, nullptr);
    const char* androidExternalPath = env->GetStringUTFChars(externalPath, nullptr);
    static EOS_Android_InitializeOptions JNIOptions = { 0 };
    JNIOptions.ApiVersion = EOS_ANDROID_INITIALIZEOPTIONS_API_LATEST;
    JNIOptions.Reserved = nullptr;
    JNIOptions.OptionalInternalDirectory = androidInternalPath;
    JNIOptions.OptionalExternalDirectory = androidExternalPath;
    SDKOptions.SystemInitializeOptions = &JNIOptions;
    EOS_EResult InitResult = EOS_Initialize(&SDKOptions);
    if(InitResult != EOS_EResult::EOS_Success) {
        return env->NewStringUTF("Error when initializing");
    }
    return env->NewStringUTF("Initialized successfully");
}

次のメソッドは SDK が 1.10 以前のバージョンの場合です。SDK バージョンが 1.11 以降の場合は、上記のメソッドを使用します。

EOS SDK のバージョンが 1.10 以前の場合、システム初期化オプションEOS_Android_InitializeOptions として定義され、ディスク アクセスのためのオプションのディレクトリ パスを含む JavaVM への参照が必要です。

EOS SDK Java 側が動作するためには、アプリケーション コンテキストを以下のように渡す必要があります。

EOSSDK.init(getApplicationContext());

ログインの例では、MainActivity クラスの onCreate でこれを行います。

これらのオプションへの正しい値を取得するには、関連づいている値を JNI を渡すことを提案します。JNIEnv* への参照によって JavaVM へ容易にアクセスできます。

JavaVM* VM = nullptr;

env->GetJavaVM(&VM);

以下は、Android での EOS SDK の完全な初期化の例です。特定のユースケースに対して調整する必要があります。

extern "C" JNIEXPORT jstring JNICALL
Java_com_example_eossdk_Documentation_initializeSdk( JNIEnv* env,
  jobject /* this */, jstring internalPath, jstring externalPath)
{
  EOS_InitializeOptions SDKOptions = { 0 };
  SDKOptions.ApiVersion = EOS_INITIALIZE_API_LATEST;
  SDKOptions.ProductName = "EOSDocumentationExample";
  SDKOptions.ProductVersion = "0.1";

  JavaVM* VM = nullptr;
  env->GetJavaVM(&VM);
  const char* androidInternalPath = env->GetStringUTFChars(internalPath, nullptr);
  const char* androidExternalPath = env->GetStringUTFChars(externalPath, nullptr);

  static EOS_Android_InitializeOptions JNIOptions = { 0 };
  JNIOptions.ApiVersion = EOS_ANDROID_INITIALIZEOPTIONS_API_LATEST;
  JNIOptions.VM = VM;

  JNIOptions.OptionalInternalDirectory = androidInternalPath;
  JNIOptions.OptionalExternalDirectory = androidExternalPath;

  SDKOptions.SystemInitializeOptions = &JNIOptions;

  EOS_EResult InitResult = EOS_Initialize(&SDKOptions);
  if(InitResult != EOS_EResult::EOS_Success){
     return env->NewStringUTF("Error when initializing");
  }
  return env->NewStringUTF("Initialized successfully");
}

5. ログイン インテントを受信する

EOS SDK が正しいログイン インテントを受け取るには、Strings.xml に使用するクライアント ID を与える必要があります。

クライアント ID は小文字でなければなりません。Android フレームワークでのスキームの一致は大文字と小文字が区別されます。常に小文字を使用してスキームを指定する必要があります。

res/values/strings.xml において、clientId を使って eos_login_protocol_scheme を設定します。

<string name="eos_login_protocol_scheme">eos.yourclientidhere</string>