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

Stay organized with collections Save and categorize content based on your preferences.

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

Download Play Core Native SDK

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

Terms and Conditions

Sửa đổi lần cuối: ngày 24 tháng Chín 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 của Đ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 API khách 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ố.
Download Play Core Native SDK

play-core-native-sdk-1.11.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á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
    55.6 MB 058b4069f09714da938656d43b6dc28d3bc6f821c9d406e9c96a1c3af014dc45
  4. Cập nhật tệp build.gradle của ứng dụng như minh họa 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/per-feature-proguard-files"
                    ...
                }
                debug {
                    ...
                }
            }
            externalNativeBuild {
                cmake {
                    path 'src/main/CMakeLists.txt'
                }
            }
        }
    
        dependencies {
            // Use the Play Core AAR included with the SDK.
            implementation files("$playcoreDir/playcore.aar")
    
            // Use the following dependency for the Play Integrity API.
            implementation("com.google.android.play:integrity:1.0.0")
            ...
        }
        

    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/per-feature-proguard-files")
                ...
            }
            debug {
                ...
            }
        }
        externalNativeBuild {
            cmake {
                path = "src/main/CMakeLists.txt"
            }
        }
    }
    
    dependencies {
        // Use the Play Core AAR included with the SDK.
        implementation(files("$playcoreDir/playcore.aar"))
        ...
    }
    
  5. Cập nhật các tệp CMakeLists.txt của ứng dụng như hình ả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
            ...)
    

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 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á

Bất cứ khi nào 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 cấp 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 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 "Next Level" (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 của bạn để xác nhận là việc tích hợp của bạn đang hoạt động chính xác.