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. SSDK gốc của Play Core bao gồm một tiêu đề C, review.h, bao gồm ReviewManager từ thư viện Đánh giá trong ứng dụng của Java 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 dùng chung có sẵn, vui lòng xem tài liệu về mô-đun gốc của Play Review.

ReviewManager_requestReviewFlow khởi đầu 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 đó. 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

下载 Play Core Native SDK

您必须先接受以下条款及条件才能下载。

条款及条件

Lần sửa đổi gần nhất: ngày 24 tháng 9 năm 2020
  1. Bằng việc sử dụng Bộ công cụ phát triển phần mềm Play Core, bạn đồng ý với các điều khoản này ngoài Điều khoản dịch vụ API của Google ("API ToS"). Nếu các điều khoản này xung đột nhau, các điều khoản này sẽ được ưu tiên áp dụng hơn Điều khoản dịch vụ API. Vui lòng đọc kỹ các điều khoản này và Điều khoản dịch vụ API.
  2. Trong phạm vi các điều khoản này, "API" có nghĩa là API của Google, các dịch vụ dành cho nhà phát triển và phần mềm liên kết khác, gồm cả Mã có thể phân phối lại.
  3. “Mã có thể phân phối lại” có nghĩa là mã đối tượng hoặc tệp tiêu đề do Google cung cấp có gọi đến API.
  4. Theo các điều khoản này và các điều khoản trong Điều khoản dịch vụ API, bạn chỉ được sao chép và phân phối Mã có thể phân phối lại để đưa vào Ứng dụng khách API của mình. Google và người cấp phép của Google sở hữu tất cả quyền, quyền sở hữu và lợi ích, bao gồm mọi tài sản sở hữu trí tuệ cũng như các quyền sở hữu riêng khác nằm trong và đối với Mã có thể phân phối lại. Bạn không được sửa đổi, dịch hoặc tạo tác phẩm phái sinh của Mã có thể phân phối lại.
  5. Google có thể thay đổi các điều khoản này bất cứ lúc nào và sẽ đưa ra thông báo, đồng thời cho phép bạn lựa chọn ngừng sử dụng Bộ công cụ phát triển phần mềm Play Core. Google sẽ đăng thông báo về các điều khoản sửa đổi tại https://developer.android.com/guide/playcore/license. Nội dung thay đổi sẽ không có hiệu lực hồi tố.

下载 Play Core Native SDK

下载 Play Core Native SDK

play-core-native-sdk-1.11.1.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ác 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 phát triển gốc bằng cách sử dụng Trình quản lý SDK để cài đặt CMake và Công cụ phát triển 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
    52.4 MB 35b25bd1d410a0e251983d8d186afb48bba62aa71c44b4c8698677f5622393e7
  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.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. Cập nhật các tệp CMakeLists.txt của ứng dụng như minh hoạ dưới đây:

    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 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 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á $playcoreDir/playcore-native-metadata.jar nhập trong tệp build.gradle.

Hãy lưu ý rằng quá trình thu thập dữ liệu này liên quan đến việc bạn sử dụng SDK gốc Play Core và việc Google sử dụng dữ liệu đã thu thập là hoạt động riêng biệt và độc lập với việc 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 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 Bài đá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 không đồng bộ thông tin mà ứng dụng của bạn cần để khởi chạy luồng bài đánh giá trong ứng dụng. Theo dõi tiến trình của thao tác ReviewManager_requestReviewFlow bằng cách gọi ReviewManager_getReviewStatus, ví dụ: một lần trong mỗi khung hiển thị. 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 bài đá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ý các 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ũng có thể kiểm tra trạng thái sử 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. Có một cách để đạt được đ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 "Cấp độ tiếp theo" trong trò chơi), như thể hiện 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 thấy để 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 đang hoạt động chính xác.