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

本指南說明如何使用原生 (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.12.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 總和檢查碼

70.9 MiB 84c9e9579f05d6e29bbbd9c9cde2fde8210947f2007866b0045f4c40fabb7368

下載連結	大小	SHA-256 總和檢查碼
	70.9 MiB	84c9e9579f05d6e29bbbd9c9cde2fde8210947f2007866b0045f4c40fabb7368

請更新應用程式的 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 呼叫的檔案中加入下列程式碼：

加入 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();

後續步驟

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