Mengintegrasikan ulasan dalam aplikasi (Native)

Panduan ini menjelaskan cara mengintegrasikan ulasan dalam aplikasi di aplikasi Anda menggunakan kode native (C atau C++). Ada panduan integrasi terpisah jika Anda menggunakan Kotlin atau Java atau Unity.

Ringkasan Native SDK

Play Core Native SDK adalah bagian dari kelompok library Google Play Core. Play Core Native SDK menyertakan file header C, review.h, yang menggabungkan ReviewManager dari library Java Play In-App Review. File header ini memungkinkan aplikasi Anda memanggil API langsung dari kode native. Untuk ringkasan fungsi publik yang tersedia, lihat dokumentasi modul native Play Review.

ReviewManager_requestReviewFlow memulai permintaan yang mengumpulkan informasi yang diperlukan untuk meluncurkan alur ulasan dalam aplikasi nanti. Anda dapat melacak hasil permintaan menggunakan ReviewManager_getReviewStatus. Untuk mengetahui informasi selengkapnya tentang semua status yang dapat ditampilkan ReviewManager_getReviewStatus, lihat ReviewErrorCode.

Baik fungsi permintaan maupun peluncuran menampilkan REVIEW_NO_ERROR jika fungsi berhasil.

Menyiapkan lingkungan pengembangan

1. Lakukan salah satu hal berikut:

   • Instal Android Studio versi 4.0 atau yang lebih tinggi. Gunakan UI SDK Manager untuk menginstal Android SDK Platform versi 10.0 (API level 29).
   • Instal alat command line Android SDK dan gunakan sdkmanager untuk menginstal Android SDK Platform versi 10.0 (API level 29).

2. Siapkan Android Studio untuk pengembangan native dengan menggunakan SDK Manager untuk menginstal CMake dan Android Native Development Kit (NDK) terbaru. Untuk informasi selengkapnya tentang membuat atau mengimpor project native, lihat Mulai Menggunakan NDK.

3. Download file zip dan ekstrak bersama project Anda.

   Link Download	Ukuran	SHA-256 Checksum
   play-core-native-sdk-1.12.1.zip	70.9 MiB	84c9e9579f05d6e29bbbd9c9cde2fde8210947f2007866b0045f4c40fabb7368

4. Update file build.gradle aplikasi Anda seperti yang ditunjukkan di bawah ini:

   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. Update file CMakeLists.txt aplikasi Anda seperti yang ditunjukkan di bawah ini:

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

Pengumpulan Data

Play Core Native SDK dapat mengumpulkan data terkait versi untuk memungkinkan Google meningkatkan produk, termasuk:

• Nama paket aplikasi
• Versi paket aplikasi
• Versi Play Core Native SDK

Data ini akan dikumpulkan saat Anda mengupload paket aplikasi ke Konsol Play. Untuk memilih tidak ikut dalam proses pengumpulan data ini, hapus impor $playcoreDir/playcore-native-metadata.jar di file build.gradle.

Perhatikan bahwa pengumpulan data ini yang terkait dengan penggunaan Play Core Native SDK oleh Anda dan penggunaan data yang dikumpulkan oleh Google terpisah dan tidak bergantung pada pengumpulan dependensi library Google yang dideklarasikan di Gradle saat Anda mengupload paket aplikasi ke Konsol Play.

Setelah Anda mengintegrasikan Play Core Native SDK ke dalam project, sertakan baris berikut di file yang berisi panggilan API:

Menyertakan review.h

Setelah mengintegrasikan Play Core Native SDK ke dalam project, sertakan baris berikut dalam file yang akan berisi panggilan API:

#include "play/review.h"

Melakukan inisialisasi Review API

Setiap kali ingin menggunakan API, Anda harus menginisialisasinya terlebih dahulu dengan memanggil fungsi ReviewManager_init, seperti yang ditunjukkan dalam contoh berikut yang dibuat dengan 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.
  }
}

Meminta alur ulasan dalam aplikasi

Ikuti panduan tentang kapan harus meminta ulasan dalam aplikasi. Panduan ini menentukan momen yang tepat untuk meminta pengguna memberikan ulasan dalam alur penggunaan aplikasi (misalnya, setelah pengguna menutup layar ringkasan di akhir level dalam game). Jika aplikasi Anda mendekati salah satu titik berikut, panggil ReviewManager_requestReviewFlow untuk secara asinkron melakukan permintaan atas informasi yang diperlukan aplikasi guna meluncurkan ulasan dalam aplikasi. Pantau perkembangan operasi ReviewManager_requestReviewFlow dengan memanggil ReviewManager_getReviewStatus, misalnya sekali setiap frame. Proses ini mungkin memerlukan waktu beberapa detik, jadi Anda harus memulai prosesnya sebelum aplikasi mencapai titik saat Anda ingin menampilkan alur ulasan dalam aplikasi.

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

Menangani status dan meluncurkan alur ulasan dalam aplikasi

Setiap kali permintaan dimulai atau alur ulasan dalam aplikasi diluncurkan, Anda dapat memeriksa statusnya menggunakan ReviewManager_getReviewStatus. Ini memungkinkan Anda untuk menentukan logika bergantung pada status API. Salah satu pendekatannya adalah dengan mempertahankan status sebagai variabel global dan memeriksa apakah statusnya adalah REVIEW_REQUEST_FLOW_COMPLETED saat pengguna melakukan tindakan tertentu (misalnya, mengetuk tombol "Level Berikutnya" di game), seperti yang ditampilkan dalam contoh berikut:

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

Jika statusnya adalah REVIEW_REQUEST_FLOW_COMPLETED dan aplikasi sudah siap, luncurkan alur ulasan dalam aplikasi:

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

Setelah meluncurkan alur ulasan dalam aplikasi, terus periksa status penyelesaian dan lanjutkan dengan alur aplikasi Anda. Cara umum untuk menangani hal ini adalah dengan mengikuti pola Game Loop.

Resource bebas

Jangan lupa untuk membebaskan resource dengan memanggil fungsi ReviewManager_destroy setelah aplikasi selesai menggunakan API (misalnya, setelah alur ulasan dalam aplikasi selesai).

void ReviewManager_destroy();

Langkah berikutnya

Uji alur ulasan dalam aplikasi untuk memverifikasi bahwa integrasi Anda berfungsi dengan benar.