アプリ内レビューを統合する(ネイティブ)

このガイドでは、ネイティブ(C または C++)コードを使用して、アプリ内レビューをアプリに統合する方法について説明します。Kotlin もしくは Java または Unity を使用している場合の統合ガイドは、個別に用意されています。

Native SDK の概要

Play Core Native SDK は Google Play Core Library ファミリーの一部です。Play Core Native SDK には、Java Play In-App Review ライブラリの ReviewManager をラップする C ヘッダー ファイル review.h が含まれています。このヘッダー ファイルを使用すると、アプリはネイティブ コードから直接 API を呼び出すことができます。利用可能なパブリック関数の概要については、Play Review ネイティブ モジュールのドキュメントをご覧ください。

ReviewManager_requestReviewFlow により、後でアプリ内レビューフローを起動するために必要な情報を収集するリクエストが開始されます。ReviewManager_getReviewStatus を使用して、リクエストの結果を追跡できます。ReviewManager_getReviewStatus が返すすべてのステータスの詳細については、ReviewErrorCode をご覧ください。

関数の実行が成功すると、Request 関数と Launch 関数の両方が REVIEW_NO_ERROR を返します。

開発環境をセットアップする

ダウンロード: Play Core Native SDK

ダウンロードする前に、次の利用規約に同意する必要があります。

利用規約

Last modified: September 24, 2020
  1. By using the Play Core Software Development Kit, you agree to these terms in addition to the Google APIs Terms of Service ("API ToS"). If these terms are ever in conflict, these terms will take precedence over the API ToS. Please read these terms and the API ToS carefully.
  2. For purposes of these terms, "APIs" means Google's APIs, other developer services, and associated software, including any Redistributable Code.
  3. “Redistributable Code” means Google-provided object code or header files that call the APIs.
  4. Subject to these terms and the terms of the API ToS, you may copy and distribute Redistributable Code solely for inclusion as part of your API Client. Google and its licensors own all right, title and interest, including any and all intellectual property and other proprietary rights, in and to Redistributable Code. You will not modify, translate, or create derivative works of Redistributable Code.
  5. Google may make changes to these terms at any time with notice and the opportunity to decline further use of the Play Core Software Development Kit. Google will post notice of modifications to the terms at https://developer.android.com/guide/playcore/license. Changes will not be retroactive.
ダウンロード Play Core Native SDK

play-core-native-sdk-1.14.0.zip

  1. 次のいずれかの操作を行います。

    • Android Studio バージョン 4.0 以降をインストールし、SDK Manager UI を使用して Android SDK Platform バージョン 10.0(API レベル 29)をインストールする。
    • Android SDK コマンドライン ツールをインストールし、sdkmanager を使用して Android SDK Platform バージョン 10.0(API レベル 29)をインストールする。
  2. Android Studio をネイティブ開発で使用できるようにするため、SDK Manager を使用して最新の CMake と Android Native Development Kit(NDK)をインストールします。ネイティブ プロジェクトの作成やインポートの詳細については、NDK のスタートガイドをご覧ください。

  3. zip ファイルをダウンロードして、プロジェクトと同じ場所に展開します。

    ダウンロード リンク サイズ SHA-256 チェックサム
    36 MiB 782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e
  4. アプリの build.gradle ファイルを以下のように更新します。

    Groovy

        // App build.gradle
    
        plugins {
          id 'com.android.application'
        }
    
        // Define a path to the extracted Play Core SDK files.
        // If using a relative path, wrap it with file() since CMake requires absolute paths.
        def playcoreDir = file('../path/to/playcore-native-sdk')
    
        android {
            defaultConfig {
                ...
                externalNativeBuild {
                    cmake {
                        // Define the PLAYCORE_LOCATION directive.
                        arguments "-DANDROID_STL=c++_static",
                                  "-DPLAYCORE_LOCATION=$playcoreDir"
                    }
                }
                ndk {
                    // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
                    abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
                }
            }
            buildTypes {
                release {
                    // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
                    proguardFile '$playcoreDir/proguard/common.pgcfg'
                    proguardFile '$playcoreDir/proguard/gms_task.pgcfg'
                    proguardFile '$playcoreDir/proguard/per-feature-proguard-files'
                    ...
                }
                debug {
                    ...
                }
            }
            externalNativeBuild {
                cmake {
                    path 'src/main/CMakeLists.txt'
                }
            }
        }
    
        dependencies {
            // Import these feature-specific AARs for each Google Play Core library.
            implementation 'com.google.android.play:app-update:2.1.0'
            implementation 'com.google.android.play:asset-delivery:2.2.2'
            implementation 'com.google.android.play:integrity:1.4.0'
            implementation 'com.google.android.play:review:2.0.1'
    
            // Import these common dependencies.
            implementation 'com.google.android.gms:play-services-tasks:18.0.2'
            implementation files("$playcoreDir/playcore-native-metadata.jar")
            ...
        }
        

    Kotlin

    // App build.gradle
    
    plugins {
        id("com.android.application")
    }
    
    // Define a path to the extracted Play Core SDK files.
    // If using a relative path, wrap it with file() since CMake requires absolute paths.
    val playcoreDir = file("../path/to/playcore-native-sdk")
    
    android {
        defaultConfig {
            ...
            externalNativeBuild {
                cmake {
                    // Define the PLAYCORE_LOCATION directive.
                    arguments += listOf("-DANDROID_STL=c++_static", "-DPLAYCORE_LOCATION=$playcoreDir")
                }
            }
            ndk {
                // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
                abiFilters.clear()
                abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")
            }
        }
        buildTypes {
            release {
                // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
                proguardFile("$playcoreDir/proguard/common.pgcfg")
                proguardFile("$playcoreDir/proguard/gms_task.pgcfg")
                proguardFile("$playcoreDir/proguard/per-feature-proguard-files")
                ...
            }
            debug {
                ...
            }
        }
        externalNativeBuild {
            cmake {
                path = "src/main/CMakeLists.txt"
            }
        }
    }
    
    dependencies {
        // Import these feature-specific AARs for each Google Play Core library.
        implementation("com.google.android.play:app-update:2.1.0")
        implementation("com.google.android.play:asset-delivery:2.2.2")
        implementation("com.google.android.play:integrity:1.4.0")
        implementation("com.google.android.play:review:2.0.1")
    
        // Import these common dependencies.
        implementation("com.google.android.gms:play-services-tasks:18.0.2")
        implementation(files("$playcoreDir/playcore-native-metadata.jar"))
        ...
    }
    
  5. アプリの CMakeLists.txt ファイルを以下のように更新します。

    cmake_minimum_required(VERSION 3.6)
    
    ...
    
    # Add a static library called “playcore” built with the c++_static STL.
    include(${PLAYCORE_LOCATION}/playcore.cmake)
    add_playcore_static_library()
    
    // In this example “main” is your native code library, i.e. libmain.so.
    add_library(main SHARED
            ...)
    
    target_include_directories(main PRIVATE
            ${PLAYCORE_LOCATION}/include
            ...)
    
    target_link_libraries(main
            android
            playcore
            ...)
    

データの収集

Play Core Native SDK は、Google がサービスを改善する目的で、バージョンに関連する次のようなデータを収集することがあります。

  • アプリのパッケージ名
  • アプリのパッケージ バージョン
  • Play Core Native SDK のバージョン

このデータは、アプリ パッケージを Google Play Console にアップロードする際に収集されます。データ収集のプロセスを無効にするには、build.gradle ファイル内の $playcoreDir/playcore-native-metadata.jar インポートを削除します。

Play Core Native SDK の使用に関連するこのデータ収集と Google によるこの収集データの使用は、Google Play Console にアプリ パッケージをアップロードする際に Gradle で宣言されるライブラリ依存関係の Google のデータ収集とは別のものであり、相互の関係はありません。

Play Core Native SDK をプロジェクトに統合したら、API 呼び出しを含むファイルに次の行を含めます。

review.h を追加する

Play Core Native SDK をプロジェクトに統合したら、API 呼び出しを含むファイルに次の行を追加します。

#include "play/review.h"

Review API を初期化する

API を使用するときは、常に ReviewManager_init 関数を呼び出して API を初期化する必要があります。android_native_app_glue.h でビルドされた次の例をご覧ください。

void android_main(android_app* app) {
  app->onInputEvent = HandleInputEvent;

  ReviewErrorCode error_code = ReviewManager_init(app->activity->vm, app->activity->clazz);
  if (error_code == REVIEW_NO_ERROR) {
    // You can use the API.
  }
}

アプリ内レビューのフローをリクエストする

アプリ内レビューをリクエストするタイミングのガイダンスに沿って、アプリのユーザーフロー内でユーザーにレビューを依頼するのに適切なポイント(たとえば、ゲームでレベルをクリアしたときに表示される概要画面をユーザーが閉じた後)を決定します。アプリでいずれかのポイントに近づいたら、ReviewManager_requestReviewFlow を呼び出して、アプリがアプリ内レビューのフローを起動するために必要な情報を非同期でリクエストします。ReviewManager_getReviewStatus を呼び出して、ReviewManager_requestReviewFlow オペレーションの進行状況をモニタリングします。たとえば、フレームごとに 1 回呼び出します。この処理には数秒かかることがあるため、アプリ内レビューのフローを表示する際は、アプリがポイントに到達する前に、このプロセスを開始する必要があります。

ReviewErrorCode error_code = ReviewManager_requestReviewFlow();
if (error_code == REVIEW_NO_ERROR) {
    // The request has successfully started, check the status using
    // ReviewManager_getReviewStatus.
} else {
    // Error such as REVIEW_PLAY_STORE_NOT_FOUND indicating that the in-app
    // review isn't currently possible.
}

ステータスを処理してアプリ内レビューのフローを起動する

リクエストが開始されるかアプリ内レビューフローが起動されるたびに、ReviewManager_getReviewStatus でステータスを確認できます。これにより、API のステータスに応じてロジックを定義できます。このための 1 つのアプローチとして、グローバル変数としてステータスを保持し、ユーザーが特定のアクション(ゲームの「次のレベル」ボタンをタップするなど)を実行したときに、ステータスが REVIEW_REQUEST_FLOW_COMPLETED であるかどうかを確認できます。次の例をご覧ください。

ReviewStatus status;
ReviewErrorCode error_code = ReviewManager_getReviewStatus(&status);
if (error_code != REVIEW_NO_ERROR) {
    // There was an error with the most recent operation.
    return;
}

switch (status) {
    case REVIEW_REQUEST_FLOW_PENDING:
        // Request is ongoing. The flow can't be launched yet.
        break;
    case REVIEW_REQUEST_FLOW_COMPLETED:
        // Request completed. The flow can be launched now.
        break;
    case REVIEW_LAUNCH_FLOW_PENDING:
        // The review flow is ongoing, meaning the dialog might be displayed.
        break;
    case REVIEW_LAUNCH_FLOW_COMPLETED:
        // The review flow has finished. Continue with your app flow (for
        // example, move to the next screen).
        break;
    default:
        // Unknown status.
        break;
}

ステータスが REVIEW_REQUEST_FLOW_COMPLETED になり、アプリの準備ができたら、アプリ内レビューフローを起動します。

// This call uses android_native_app_glue.h.
ReviewErrorCode error_code = ReviewManager_launchReviewFlow(app->activity->clazz);
if (error_code != REVIEW_NO_ERROR) {
    // There was an error while launching the flow.
    return;
}

アプリ内レビューフローを起動したら、ステータスの完了をチェックしながら、アプリのフローを続行します。ゲームループのパターンに沿ってこの処理を行うのが一般的な方法です。

リソースを解放する

アプリが API の使用を終了したとき(たとえば、アプリ内レビューフローが完了したとき)は、ReviewManager_destroy 関数を呼び出してリソースを解放する必要があります。

void ReviewManager_destroy();

次のステップ

アプリのアプリ内レビューフローをテストして、統合が正しく機能していることを検証します。