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

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

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

play-core-native-sdk-1.12.1.zip

  1. 執行下列其中一項操作:

  2. 使用 SDK Manager 安裝最新的 CMake 和 Android Native Development Kit (NDK),讓 Android Studio 準備進行原生開發。如要進一步瞭解如何建立或匯入原生專案,請參閱 NDK 入門指南

  3. 下載 ZIP 檔案,然後將其連同專案一起解壓縮。

    下載連結 大小 SHA-256 總和檢查碼
    70.9 MiB 84c9e9579f05d6e29bbbd9c9cde2fde8210947f2007866b0045f4c40fabb7368
  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.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"))
        ...
    }
    
  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 原生 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();

後續步驟

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