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

Download Play Core Native SDK

Sebelum mendownload, Anda harus menyetujui ketentuan dan persyaratan berikut.

Persyaratan dan Ketentuan

Terakhir diubah: 24 September 2020

Dengan menggunakan Software Development Kit Play Core, Anda menyetujui persyaratan ini bersama dengan Persyaratan Layanan Google API ("ToS API"). Jika persyaratan ini bertentangan dengan ToS API, persyaratan ini akan lebih diutamakan. Baca persyaratan ini dan ToS API dengan saksama.
Untuk tujuan persyaratan ini, "API" berarti API Google, layanan developer lainnya, dan software terkait, termasuk Kode yang Dapat Didistribusikan Ulang.
“Kode yang Dapat Didistribusikan Ulang” berarti kode objek atau file header yang disediakan Google yang memanggil API.
Tunduk pada persyaratan ini dan persyaratan ToS API, Anda dapat menyalin dan mendistribusikan Kode yang Dapat Didistribusikan Ulang hanya untuk disertakan sebagai bagian dari Klien API Anda. Google dan pemegang lisensinya memiliki semua hak, kepemilikan, dan kepentingan, termasuk setiap dan semua hak atas kekayaan intelektual dan hak milik eksklusif lainnya, atas dan untuk Kode yang Dapat Didistribusikan Ulang. Anda tidak akan memodifikasi, menerjemahkan, atau membuat karya turunan dari Kode yang Dapat Didistribusikan Ulang.
Google dapat melakukan perubahan pada persyaratan ini kapan saja dengan pemberitahuan dan kesempatan untuk menolak penggunaan Software Development Kit Play Core lebih lanjut. Google akan memposting pemberitahuan terkait perubahan persyaratan ini di https://developer.android.com/guide/playcore/license. Perubahan tidak berlaku surut.

Saya telah membaca dan menyetujui ketentuan dan persyaratan di atas

Download Play Core Native SDK

play-core-native-sdk-1.13.0.zip

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 (level API 29).
- Instal alat command line Android SDK dan gunakan sdkmanager untuk menginstal Android SDK Platform versi 10.0 (level API 29).
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.
Download file zip dan ekstrak bersama project Anda.

Link Download Ukuran Checksum SHA-256

35,6 MiB 4eee8aafbe0309c0b4ba377c7c7bc1986c73ae70dd7ce3a04f792e1a67d79d51

Link Download	Ukuran	Checksum SHA-256
	35,6 MiB	4eee8aafbe0309c0b4ba377c7c7bc1986c73ae70dd7ce3a04f792e1a67d79d51

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

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.