本指南說明如何使用原生 (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 發布條款修訂通知。變更將不溯及既往。
執行下列其中一項操作:
- 安裝 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 請更新應用程式的
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();
後續步驟
測試應用程式內評論流程,以確認這項整合機制能正常運作。