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

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

原生 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。

設定開發環境

下載 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.15.3.zip

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

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

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

    下載連結 大小 SHA-256 總和檢查碼
    37.8 MiB 9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

  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.3.0'
        implementation 'com.google.android.play:integrity:1.4.0'
        implementation 'com.google.android.play:review:2.0.2'

        // 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.3.0")
    implementation("com.google.android.play:integrity:1.4.0")
    implementation("com.google.android.play:review:2.0.2")

    // 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();

後續步驟

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