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

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

原生 SDK 總覽

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

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

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

設定開發環境

如要設定開發環境,請按照 Play Core 程式庫指南中「原生」一節的操作說明進行設定。

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

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

後續步驟

測試應用程式的應用程式內評論流程,驗證整合作業是否正常運行。