Tích hợp các bài đánh giá trong ứng dụng (Gốc)

Hướng dẫn này mô tả cách tích hợp bài đánh giá trong ứng dụng sử dụng mã gốc (C hoặc C++). Sẽ có các hướng dẫn tích hợp riêng nếu bạn đang sử dụng Kotlin hoặc Java hoặc Unity.

Tổng quan về SDK gốc (native SDK)

SDK gốc của Play Core là một phần của nhóm thư viện Google Play Core. SDK gốc của Play Core bao gồm một tệp tiêu đề C tên gọi review.h, có chứa ReviewManager từ thư viện Java Đánh giá trong ứng dụng trên Play. Tệp tiêu đề này cho phép ứng dụng gọi API trực tiếp từ mã gốc. Để biết thông tin tổng quan về các hàm công khai được hỗ trợ, vui lòng xem tài liệu về mô-đun gốc của bài đánh giá trên Play.

ReviewManager_requestReviewFlow khởi động một yêu cầu thu thập thông tin cần thiết để khởi chạy luồng bài đánh giá trong ứng dụng sau này. Bạn có thể theo dõi kết quả của yêu cầu bằng cách sử dụng ReviewManager_getReviewStatus. Để biết thêm thông tin về tất cả trạng thái mà ReviewManager_getReviewStatus có thể trả về, hãy xem ReviewErrorCode.

Cả hàm yêu cầu và hàm khởi chạy đều trả về REVIEW_NO_ERROR nếu hàm thành công.

Thiết lập môi trường phát triển

Download Play Core Native SDK

Before downloading, you must agree to the following terms and conditions.

Terms and Conditions

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.
Download Play Core Native SDK

play-core-native-sdk-1.14.0.zip

  1. Thực hiện một trong hai cách sau:

    • Cài đặt Android Studio phiên bản 4.0 trở lên. Sử dụng giao diện người dùng Trình quản lý SDK để cài đặt Nền tảng SDK Android phiên bản 10.0 (API cấp 29).
    • Cài đặt công cụ dòng lệnh của SDK Android và sử dụng sdkmanager để cài đặt Nền tảng SDK Android phiên bản 10.0 (API cấp 29).

  2. Chuẩn bị Android Studio cho việc phát triển bằng mã gốc bằng cách dùng Trình quản lý SDK để cài đặt CMake và Bộ phát triển mã gốc Android (NDK) mới nhất. Để biết thêm thông tin về việc tạo hoặc nhập các dự án gốc, xem Bắt đầu với NDK.

  3. Tải tệp zip xuống và giải nén cùng dự án của bạn.

    Đường liên kết để tải xuống Kích thước Giá trị tổng kiểm SHA-256
    36 MiB 782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e

  4. Cập nhật tệp build.gradle của ứng dụng như minh hoạ dưới đây:

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

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

    // Import these common dependencies.
    implementation("com.google.android.gms:play-services-tasks:18.0.2")
    implementation(files("$playcoreDir/playcore-native-metadata.jar"))
    ...
}

  5. Cập nhật các tệp CMakeLists.txt của ứng dụng như bên dưới:

    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
        ...)

Thu thập dữ liệu

SDK gốc của Play Core có thể thu thập một số dữ liệu liên quan đến phiên bản để cho phép Google cải thiện sản phẩm, trong đó có:

  • Tên gói của ứng dụng
  • Phiên bản gói của ứng dụng
  • Phiên bản SDK gốc của Play Core

Dữ liệu này sẽ được thu thập khi bạn tải gói ứng dụng lên Play Console. Để chọn không tham gia quá trình thu thập dữ liệu này, hãy xoá việc nhập $playcoreDir/playcore-native-metadata.jar trong tệp build.gradle.

Lưu ý: việc thu thập dữ liệu này liên quan đến việc bạn sử dụng SDK gốc của Play Core. Bên cạnh đó, việc Google sử dụng dữ liệu đã thu thập là riêng biệt cũng như độc lập với việc Google thu thập các phần phụ thuộc của thư viện được khai báo trong Gradle khi bạn tải gói ứng dụng lên Play Console.

Sau khi bạn tích hợp SDK gốc của Play Core vào dự án của mình, hãy đưa dòng sau đây vào các tệp chứa lệnh gọi API:

Bao gồm review.h

Sau khi tích hợp SDK gốc của Play Core vào dự án, hãy đưa dòng sau vào các tệp chứa lệnh gọi API:

#include "play/review.h"

Khởi chạy API Đánh giá

Mỗi khi muốn sử dụng API, trước tiên bạn phải khởi chạy API bằng cách gọi hàm ReviewManager_init, như trong ví dụ dưới đây được tạo bằng 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.
  }
}

Yêu cầu luồng bài đánh giá trong ứng dụng

Làm theo hướng dẫn về thời điểm yêu cầu đánh giá trong ứng dụng để xác định điểm tốt trong luồng người dùng ứng dụng nhằm nhắc họ đánh giá (ví dụ: sau khi người dùng đóng màn hình tóm tắt ở cuối màn chơi trong trò chơi). Khi ứng dụng đến gần một trong các điểm này, hãy gọi ReviewManager_requestReviewFlow để yêu cầu một cách không đồng bộ thông tin mà ứng dụng của bạn cần để khởi chạy luồng đánh giá trong ứng dụng. Theo dõi tiến trình của hoạt động ReviewManager_requestReviewFlow bằng cách gọi ReviewManager_getReviewStatus, ví dụ: một lần mỗi khung hình. Quá trình này có thể mất vài giây, vì vậy bạn cần bắt đầu quá trình này trước khi ứng dụng đạt đến điểm bạn muốn hiển thị luồng đánh giá trong ứng dụng.

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.
}

Xử lý trạng thái và khởi chạy luồng bài đánh giá trong ứng dụng

Bất cứ khi nào một yêu cầu bắt đầu hoặc luồng bài đánh giá được khởi chạy trong ứng dụng, bạn có thể kiểm tra trạng thái bằng cách dùng ReviewManager_getReviewStatus. Điều này cho phép bạn xác định logic dựa trên trạng thái của API. Một cách để thực hiện điều này là giữ trạng thái làm một biến toàn cục và kiểm tra xem trạng thái đó có phải là REVIEW_REQUEST_FLOW_COMPLETED hay không khi người dùng thực hiện một thao tác nào đó (ví dụ: nhấn vào nút "Màn kế tiếp" trong trò chơi), như trong ví dụ sau:

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;
}

Khi trạng thái là REVIEW_REQUEST_FLOW_COMPLETED và ứng dụng của bạn đã sẵn sàng, hãy chạy luồng bài đánh giá trong ứng dụng:

// 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;
}

Sau khi khởi chạy luồng bài đánh giá trong ứng dụng, hãy tiếp tục kiểm tra trạng thái hoàn thành và tiếp tục luồng ứng dụng của bạn. Cách thường dùng để xử lý trường hợp này là làm theo mẫu Vòng lặp trò chơi.

Giải phóng tài nguyên

Đừng quên giải phóng tài nguyên bằng cách gọi hàm ReviewManager_destroy sau khi ứng dụng của bạn sử dụng xong API (ví dụ: sau khi hoàn tất luồng bài đánh giá trong ứng dụng).

void ReviewManager_destroy();

Các bước tiếp theo

Kiểm thử luồng bài đánh giá trong ứng dụng để xác nhận rằng việc tích hợp của bạn hoạt động chính xác.