整合應用程式內評論 (原生)

本指南說明如何使用原生 (C 或 C++) 程式碼將應用程式內評論整合至您的應用程式中。如果您使用的是 Kotlin 或 Java 或 Unity，請參閱不同的整合指南。

原生 SDK 總覽

Play Core 原生 SDK 屬於 Google Play Core 程式庫系列的一部分。Play Core 原生 SDK 包含 C 標頭檔案 review.h，可納入 Java Play 應用程式內評論程式庫中的 ReviewManager。應用程式可利用這個標頭檔案，直接從原生程式碼呼叫 API。如需可用公開函式的總覽，請參閱 Play Review 原生模組說明文件。

ReviewManager_requestReviewFlow 會發出要求，以便收集稍後啟動應用程式內評論流程所需的資訊。您可以使用 ReviewManager_getReviewStatus 追蹤要求的結果。如要進一步瞭解 ReviewManager_getReviewStatus 可傳回的所有狀態，請參閱 ReviewErrorCode 的說明。

如果函式執行成功，則要求和啟動函式皆會傳回 REVIEW_NO_ERROR。

設定開發環境

Download Play Core Native SDK

Before downloading, you must agree to the following terms and conditions.

Terms and Conditions

上次修改時間：2020 年 9 月 24 日

使用 Play Core 軟體開發套件，即表示您同意遵守本條款，以及《Google API 服務條款》(以下簡稱「API 服務條款」)。如果本條款與 API 服務條款相牴觸，應以本條款為準。請詳閱本條款和 API 服務條款。
就本條款而言，「API」是指 Google 的 API、其他開發人員服務和相關軟體，包括任何可轉散發程式碼。
「可轉散發程式碼」是指 Google 提供的物件程式碼或標頭檔案，用於呼叫 API。
根據本條款和 API 服務條款的規定，您可以複製並發布可轉散發程式碼，但只能納入為 API 用戶端的一部分。Google 及其授權人對「可轉散發的程式碼」擁有所有權利、所有權和利益，包括任何和所有智慧財產權及其他所有權益。您不得對可轉散發程式碼進行修改、翻譯或製造衍生作品。
Google 可隨時變更本條款。條款有所異動時，Google 會發出通知並提供選項，讓開發人員可以拒絕繼續使用 Play Core 軟體開發套件。Google 將於 https://developer.android.com/guide/playcore/license 發布條款修訂通知。變更將不溯及既往。

I have read and agree with the above terms and conditions

Download Play Core Native SDK

play-core-native-sdk-1.11.1.zip

執行下列其中一項操作：
- 安裝 Android Studio 4.0 以上版本。使用 SDK Manager UI 安裝 Android SDK Platform 10.0 版 (API 級別 29)。
- 安裝 Android SDK 指令列工具，並使用 sdkmanager 安裝 Android SDK Platform 10.0 版 (API 級別 29)。
使用 SDK Manager 安裝最新的 CMake 和 Android Native Development Kit (NDK)，讓 Android Studio 準備進行原生開發。如要進一步瞭解如何建立或匯入原生專案，請參閱 NDK 入門指南。
下載 ZIP 檔案，然後將其連同專案一起解壓縮。

下載連結大小 SHA-256 總和檢查碼

52.4 MB 35b25bd1d410a0e251983d8d186afb48bba62aa71c44b4c8698677f5622393e7

下載連結	大小	SHA-256 總和檢查碼
	52.4 MB	35b25bd1d410a0e251983d8d186afb48bba62aa71c44b4c8698677f5622393e7

請更新應用程式的 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.0.0'
        implementation 'com.google.android.play:asset-delivery:2.0.0'
        implementation 'com.google.android.play:integrity:1.0.1'
        implementation 'com.google.android.play:review:2.0.0'

        // 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.0.0")
    implementation("com.google.android.play:asset-delivery:2.0.0")
    implementation("com.google.android.play:integrity:1.0.1")
    implementation("com.google.android.play:review:2.0.0")

    // Import these common dependencies.
    implementation("com.google.android.gms:play-services-tasks:18.0.2")
    implementation(files("$playcoreDir/playcore-native-metadata.jar"))
    ...
}

請更新應用程式的 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 原生 SDK 可收集版本相關資料，讓 Google 能夠改善產品，這包括：

應用程式的套件名稱
應用程式的套件版本
Play Core 原生 SDK 版本

當您將應用程式套件上傳至 Play 管理中心時，系統就會收集這類資料。如要選擇退出此資料收集程序，請移除 build.gradle 檔案中的 $playcoreDir/playcore-native-metadata.jar 匯入項目。

請注意，上述與使用 Play Core 原生 SDK 相關的資料收集行為，以及 Google 使用所收集資料的行為，與您在上傳應用程式套件至 Play 管理中心時，Google 收集 Gradle 中宣告的程式庫依附元件無關。

將 Play Core 原生 SDK 整合到專案後，請在包含 API 呼叫的檔案中加入下列程式碼：

Include review.h

將 Play Core 原生 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 作業的進度，例如每幅畫面一次。這項作業最多可能需要數秒鐘的時間，因此您應在應用程式到達預定要顯示應用程式內評論流程的時間點之前啟動這項程序。

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 狀態定義邏輯。其中一個方法是將狀態保留為全域變數，並檢查在使用者執行特定動作 (例如，在遊戲中輕觸「下一關」(Next Level) 按鈕) 時，狀態是否為 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();

後續步驟

測試應用程式內評論流程，以確認這項整合機制能正常運作。