Penyiapan

Halaman ini menjelaskan cara menyiapkan aplikasi, game, atau SDK untuk menggunakan Play Integrity API. Untuk mengintegrasikan API, Anda harus memiliki project Google Cloud, yang diperlukan untuk mulai membuat permintaan. Kemudian, Anda dapat menautkan project Google Cloud di Konsol Google Play (untuk aplikasi) atau Google Play SDK Console (untuk SDK). Project Anda harus ditautkan untuk mengakses opsi konfigurasi tambahan, fitur pengujian, pelaporan API, dan untuk meminta peningkatan kuota permintaan harian Anda.

Aktifkan Play Integrity API

Setiap aplikasi atau SDK yang memanggil Play Integrity API harus memiliki project Google Cloud untuk menggunakan API dan memantau penggunaan. Ini adalah langkah pertama yang wajib dilakukan untuk semua integrasi. Anda dapat mengaktifkan Play Integrity API di Konsol Google Cloud atau Anda dapat langsung melewati penautan project Cloud ke Google Play dan Play Integrity API akan diaktifkan untuk Anda.

Di Konsol Google Cloud, buat project Cloud baru atau pilih project Cloud yang sudah ada dan ingin Anda gunakan dengan Play Integrity API.

  1. Buka APIs and services.
  2. Pilih Enable APIs and services.
  3. Telusuri Play Integrity API.
  4. Klik Enable.

Sekarang Anda dapat mengintegrasikan Play Integrity API ke dalam aplikasi Anda. Untuk mengakses fitur lanjutan dan peningkatan kuota, Anda harus melanjutkan ke langkah penautan.

Tautkan ke Google Play (direkomendasikan)

Tautkan aplikasi atau SDK Anda ke Google Play menggunakan petunjuk ini.

Untuk aplikasi dan game di Google Play

Aplikasi yang didistribusikan di Google Play harus menautkan project Google Cloud mereka di Konsol Google Play untuk mengaktifkan fitur tambahan dan meminta peningkatan kuota API harian.

  1. Buka Konsol Google Play, lalu pilih aplikasi Anda.
  2. Buka Pengujian dan rilis > Integritas aplikasi.
  3. Di bagian Play Integrity API, klik Tautkan project Cloud.
  4. Pilih project Google Cloud yang akan Anda gunakan dengan Play Integrity API; jika Play Integrity API belum diaktifkan untuk project tersebut, API akan diaktifkan secara otomatis setelah penautan.

Untuk penyedia SDK di Play SDK Console

Penyedia SDK yang menggunakan Google Play SDK Console dapat menautkan project Google Cloud mereka untuk mengatribusikan penggunaan API ke SDK, bukan ke masing-masing aplikasi yang menggunakannya, mengaktifkan fitur tambahan, dan meminta peningkatan kuota API harian. Perhatikan bahwa akses ke Google Play SDK Console tunduk pada kriteria kelayakan.

  1. Buka Google Play SDK Console, lalu pilih SDK Anda.
  2. Buka Integritas SDK
  3. Di bagian Play Integrity API, klik Tautkan project Cloud.
  4. Pilih project Google Cloud yang akan Anda gunakan dengan Play Integrity API; jika Play Integrity API belum diaktifkan untuk project tersebut, API akan diaktifkan secara otomatis setelah ditautkan.

Memahami batas penggunaan Play Integrity API

Aplikasi atau SDK Anda memiliki batas harian default sebanyak 10.000 total permintaan, yang terkait dengan Nomor Project Cloud yang terkait. Jika memperkirakan volume yang lebih tinggi, Anda dapat meminta penambahan kuota.

Tindakan Kuota harian Catatan
Permintaan token 10.000 Dibagikan antara permintaan klasik dan persiapan token standar
Dekripsi token di server Google 10.000 Dibagikan antara permintaan klasik dan standar

Meningkatkan jumlah maksimum permintaan harian Anda

Peningkatan kuota tunduk pada kriteria kelayakan. Peningkatan kuota berlaku untuk panggilan pembuatan token sisi klien dan panggilan dekripsi sisi server. Pemrosesan permintaan dapat memerlukan waktu hingga satu minggu. Sebaiknya pantau penggunaan Play Integrity API di Konsol Google Cloud dan tetapkan pemberitahuan kuota untuk menghindari gangguan pada layanan Anda.

Meskipun dengan kuota yang lebih tinggi, terus batasi permintaan klasik untuk tindakan yang jarang dan bernilai tinggi guna menghemat penggunaan data dan baterai pengguna.

Untuk aplikasi dan game di Google Play

Agar memenuhi syarat untuk mendapatkan peningkatan kuota, aplikasi Anda harus tersedia di Google Play selain di saluran distribusi lainnya. Anda harus menautkan project Google Cloud ke aplikasi di Konsol Play. Permintaan kuota dari project yang tidak ditautkan akan ditolak.

Untuk meminta penambahan kuota:

  1. Tautkan project Google Cloud yang relevan di Konsol Play.
  2. Pastikan Anda telah menerapkan logika API dengan benar, termasuk strategi percobaan ulang yang tepat.
  3. Kirimkan formulir permintaan kuota.

Untuk penyedia SDK di Play SDK Console

Agar memenuhi syarat untuk mendapatkan penambahan kuota, SDK Anda harus diklaim di Google Play SDK Console dan project Cloud Anda harus ditautkan ke SDK Anda di sana. Akses ke Google Play SDK Console tunduk pada kriteria kelayakan.

Untuk meminta penambahan kuota:

  1. Tautkan project Google Cloud Anda di Google Play SDK Console.
  2. Lengkapi formulir dukungan Google Play SDK Console.

Di bagian komentar terbuka, jelaskan kasus penggunaan Anda, jenis permintaan API yang Anda buat (standar atau klasik atau keduanya), seberapa sering Anda membuat permintaan, dan jumlah maksimum permintaan harian yang Anda inginkan.

Mengintegrasikan Play Integrity API ke dalam aplikasi Anda

Untuk mengintegrasikan Play Integrity API ke dalam aplikasi atau SDK Anda, lakukan salah satu hal berikut, bergantung pada lingkungan pengembangan Anda:

Kotlin atau Java

Library Android terbaru untuk Play Integrity API tersedia dari Repositori Maven Google. Tambahkan dependensi berikut ke file build.gradle aplikasi Anda:

implementation 'com.google.android.play:integrity:1.6.0'

Unity

Bagian berikut menjelaskan cara mengintegrasikan dan menyiapkan Google Play Integrity API untuk project Unity, yang mencakup versi Unity yang didukung, metode penginstalan, dan penyiapan lingkungan.

Versi Unity yang didukung

  • Semua versi 2019.x, 2020.x, dan yang lebih baru didukung.
  • Jika Anda menggunakan Unity 2018.x, versi 2018.4 atau yang lebih baru didukung.
  • Unity 2017.x dan yang lebih lama tidak didukung.

Menyiapkan lingkungan pengembangan

OpenUPM-CLI

Jika Anda telah menginstal OpenUPM CLI, Anda dapat menginstal registry OpenUPM dengan perintah berikut:

openupm add com.google.play.integrity

OpenUPM

  1. Buka setelan pengelola paket dengan memilih opsi menu Unity Edit > Project Settings > Package Manager.

  2. Tambahkan OpenUPM sebagai registry tercakup ke jendela Package Manager:

    Name: package.openupm.com
URL: https://package.openupm.com
Scopes: com.google.external-dependency-manager
  com.google.play.common
  com.google.play.core
  com.google.play.integrity

  3. Buka menu package manager dengan memilih opsi menu Unity Window > Package Manager.

  4. Tetapkan drop-down cakupan pengelola untuk memilih Registri Saya.

  5. Pilih paket plugin Google Play Integrity untuk Unity dari daftar paket, lalu tekan Install.

Mengimpor dari GitHub

  1. Download rilis .unitypackage terbaru dari GitHub.

  2. Impor file .unitypackage dengan memilih opsi menu Unity Assets > Import package > Custom Package, lalu mengimpor semua item.

Unreal Engine

Bagian berikut menjelaskan cara mengintegrasikan dan menyiapkan Google Play Integrity API untuk project Unreal Engine.

Versi Unreal Engine yang didukung

Plugin ini mendukung Unreal Engine 5.0 dan semua versi berikutnya.

Menyiapkan lingkungan pengembangan

  1. Download Plugin Unreal Engine Play dari repositori GitHub.

  2. Salin folder GooglePlay di dalam folder Plugins di project Unreal Engine Anda.

  3. Buka project Unreal Engine Anda, lalu klik Edit → Plugins.

  4. Cari Google Play, lalu centang kotak Diaktifkan.

  5. Mulai ulang project game dan picu build.

  6. Buka file Build.cs project Anda dan tambahkan modul PlayIntegrity ke PublicDependencyModuleNames:

    using UnrealBuildTool;

public class MyGame : ModuleRules
{
  public MyGame(ReadOnlyTargetRules Target) : base(Target)
  {
    // ...

    PublicDependencyModuleNames.Add("PlayIntegrity");

    // ...
  }
}

Native

Ikuti panduan penyiapan native. Untuk mengetahui detail selengkapnya, lihat dokumentasi referensi API native Play Integrity.

Mengonfigurasi respons API (opsional)

Respons API menyertakan verdict default yang ditampilkan dalam setiap permintaan. Jika telah menautkan project Cloud di Konsol Play atau SDK Console Play, Anda dapat menyesuaikan respons API untuk menyertakan informasi tambahan.

Verdict integritas default

Verdict integritas berikut ditampilkan dalam respons Play Integrity API secara default:

Kolom respons Nilai Deskripsi
Integritas perangkat MEETS_DEVICE_INTEGRITY Aplikasi berjalan di perangkat Android asli dan bersertifikasi. Di Android 13 dan yang lebih tinggi, ada bukti yang didukung hardware bahwa bootloader perangkat terkunci dan Android OS yang dimuat adalah image produsen perangkat bersertifikasi.
Kosong (nilai kosong) Aplikasi berjalan di perangkat yang memiliki tanda-tanda serangan (seperti hooking API) atau penyusupan sistem (seperti di-root), atau aplikasi tidak berjalan di perangkat fisik (seperti emulator yang tidak lulus pemeriksaan integritas Google Play).
Detail akun Play LICENSED Pengguna memiliki hak aplikasi. Dengan kata lain, pengguna menginstal atau mengupdate aplikasi Anda dari Google Play di perangkatnya.
UNLICENSED Pengguna tidak memiliki hak aplikasi. Hal ini terjadi saat, misalnya, pengguna melakukan sideload pada aplikasi Anda atau tidak menginstalnya dari Google Play.
UNEVALUATED Detail pemberian lisensi tidak dievaluasi karena persyaratan tidak terpenuhi. Hal ini dapat terjadi karena beberapa alasan, termasuk:
  • Perangkat tidak cukup tepercaya.
  • Pengguna tidak login ke Google Play.
  • Versi aplikasi yang diinstal di perangkat tidak dikenal oleh Google Play.
Integritas aplikasi PLAY_RECOGNIZED Aplikasi dan sertifikat cocok dengan versi yang didistribusikan oleh Google Play.
UNRECOGNIZED_VERSION Nama paket atau sertifikat tidak cocok dengan data Google Play.
UNEVALUATED Integritas aplikasi tidak dievaluasi. Persyaratan yang diperlukan tidak terpenuhi, seperti perangkat tidak cukup tepercaya.

Google Play Game untuk PC

Jika mendistribusikan aplikasi ke Google Play Game untuk PC, Anda akan otomatis diikutsertakan untuk menerima label tambahan dalam verdict integritas perangkat:

Kolom respons Label Deskripsi
Integritas perangkat MEETS_VIRTUAL_INTEGRITY Aplikasi berjalan di Android emulator yang didukung oleh layanan Google Play. Emulator lulus pemeriksaan integritas sistem dan memenuhi persyaratan kompatibilitas inti Android.

Verdict integritas opsional

Jika telah menautkan project Cloud di Konsol Play atau SDK Console Play, Anda dapat memilih untuk menerima informasi tambahan.

Untuk melakukan perubahan, buka Konsol Play, lalu buka Pengujian dan rilis > Integritas aplikasi. Di samping Play Integrity API, klik Setelan. Klik Ubah respons, edit dan simpan perubahan Anda.

Informasi perangkat

Label perangkat tambahan dalam verdict deviceIntegrity memberi tahu Anda lebih lanjut tentang lingkungan perangkat tempat aplikasi berjalan. Satu perangkat menampilkan beberapa label jika memenuhi kriteria untuk setiap label. Anda dapat menggunakan label ini untuk membuat strategi penegakan kebijakan bertingkat. Misalnya, Anda dapat memilih untuk memercayai perangkat yang menampilkan tiga label (MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY, dan MEETS_BASIC_INTEGRITY) lebih dari perangkat yang hanya menampilkan satu label (MEETS_BASIC_INTEGRITY).

Atribut perangkat memberi tahu Anda versi Android SDK dari Android OS di perangkat. Pada masa mendatang, fitur ini dapat diperluas dengan atribut perangkat lainnya.

Aktivitas perangkat terbaru menampilkan tingkat yang berkisar dari LEVEL_1 (jumlah permintaan rendah) hingga LEVEL_4 (jumlah permintaan tinggi). Tingkat aktivitas yang tinggi dapat menunjukkan bahwa perangkat digunakan untuk menghasilkan token berlebihan untuk distribusi yang tidak sah ke perangkat yang tidak tepercaya.

Panggilan kembali perangkat memungkinkan Anda menyimpan beberapa data khusus per perangkat dengan perangkat tertentu yang dapat Anda ambil secara andal saat aplikasi Anda diinstal ulang nanti di perangkat yang sama.

Setelah Anda memilih untuk menyertakan informasi opsional, respons API Anda akan menyertakan kolom dan respons baru dalam verdict:

Kolom respons Label Deskripsi
Integritas perangkat MEETS_BASIC_INTEGRITY Aplikasi berjalan di perangkat yang telah lulus pemeriksaan integritas sistem dasar. Bootloader perangkat dapat dikunci atau tidak dikunci, dan status booting dapat diverifikasi atau tidak diverifikasi. Perangkat mungkin tidak tersertifikasi, dalam hal ini Google tidak dapat memberikan jaminan keamanan, privasi, atau kompatibilitas aplikasi. Di Android 13 dan yang lebih tinggi, verdict MEETS_BASIC_INTEGRITY mengharuskan root of trust pengesahan disediakan oleh Google.
MEETS_STRONG_INTEGRITY Aplikasi berjalan di perangkat Android asli dan bersertifikasi dengan update keamanan terbaru.
  • Di Android 13 dan yang lebih tinggi, putusan MEETS_STRONG_INTEGRITY memerlukan MEETS_DEVICE_INTEGRITY dan update keamanan dalam setahun terakhir untuk semua partisi perangkat, termasuk patch partisi OS Android dan patch partisi vendor.
  • Di Android 12 dan yang lebih lama, putusan MEETS_STRONG_INTEGRITY hanya memerlukan bukti integritas booting yang didukung hardware dan tidak memerlukan perangkat untuk memiliki update keamanan terbaru. Oleh karena itu, saat menggunakan MEETS_STRONG_INTEGRITY, sebaiknya pertimbangkan juga versi Android SDK di kolom deviceAttributes.
Atribut perangkat sdkVersion: 19, 20, ..., 36 Versi SDK Android OS yang berjalan di perangkat. Angka yang ditampilkan dipetakan ke Build.VERSION_CODES.
Kosong (nilai kosong) Versi SDK tidak dievaluasi karena persyaratan yang diperlukan tidak terpenuhi. Dalam hal ini, kolom sdkVersion tidak ditetapkan; jadi, kolom deviceAttributes kosong. Hal ini dapat terjadi karena:
  • Perangkat tidak cukup tepercaya.
  • Terjadi masalah teknis pada perangkat.
Permintaan token integritas API standar di perangkat ini dalam satu jam terakhir per aplikasi Permintaan token integritas API klasik di perangkat ini dalam satu jam terakhir per aplikasi
Aktivitas perangkat terbaru LEVEL_1 (terendah) 10 atau lebih sedikit 5 atau kurang
LEVEL_2 Antara 11 dan 25 Antara 6 dan 10
LEVEL_3 Antara 26 dan 50 Antara 11 dan 15
LEVEL_4 (tertinggi) Lebih dari 50 Lebih dari 15
UNEVALUATED Aktivitas perangkat terbaru tidak dievaluasi. Hal ini dapat terjadi karena:
  • Perangkat tidak cukup tepercaya.
  • Versi aplikasi yang diinstal di perangkat tidak dikenal oleh Google Play.
  • Terjadi masalah teknis pada perangkat.
Penarikan perangkat values: bitFirst, bitSecond, bitThird Ini adalah nilai bit yang Anda tetapkan di masa lalu untuk perangkat tertentu. Anda memutuskan arti setiap bit. Tiga nilai bit adalah false secara default.
writeDates: yyyymmFirst, yyyymmSecond, yyyymmThird Ini adalah tanggal penulisan nilai bit dalam UTC yang akurat hingga tahun dan bulan. Tanggal penulisan bit panggil balik diperbarui setiap kali bit disetel ke benar (true) dan dihapus saat bit disetel ke salah (false).

Detail lingkungan

Risiko akses aplikasi memberi tahu Anda apakah ada aplikasi lain yang sedang berjalan yang dapat digunakan untuk merekam layar, menampilkan overlay, atau mengontrol perangkat. Layanan aksesibilitas terverifikasi yang dikenal oleh Google Play otomatis dikecualikan dari verdict ini.

Verdict Play Protect memberi tahu Anda apakah Google Play Protect diaktifkan di perangkat dan apakah Google Play Protect telah menemukan malware yang diketahui.

Setelah Anda memilih untuk menyertakan informasi opsional, respons API Anda akan menyertakan kolom dan respons baru dalam verdict:

Kolom respons Nilai Deskripsi
Verdict risiko akses aplikasi KNOWN_INSTALLED Aplikasi diinstal oleh Google Play atau dimuat sebelumnya di partisi sistem oleh produsen perangkat.
KNOWN_CAPTURING Aplikasi yang diinstal oleh Google Play atau yang dimuat sebelumnya di perangkat sedang berjalan dan dapat digunakan untuk membaca atau merekam input dan output aplikasi yang meminta, seperti aplikasi perekaman layar.
KNOWN_CONTROLLING Aplikasi yang diinstal oleh Google Play atau dimuat sebelumnya di perangkat sedang berjalan dan dapat digunakan untuk mengontrol perangkat serta input dan output aplikasi yang meminta, seperti aplikasi yang mengontrol dari jarak jauh.
KNOWN_OVERLAYS Aplikasi yang diinstal oleh Google Play atau dimuat sebelumnya di perangkat sedang berjalan dan mungkin menampilkan overlay di aplikasi yang meminta.
UNKNOWN_INSTALLED Aplikasi lain diinstal, yang tidak diinstal oleh Google Play atau dimuat sebelumnya di partisi sistem oleh produsen perangkat.
UNKNOWN_CAPTURING Aplikasi lain yang dapat digunakan untuk membaca atau merekam input dan output aplikasi yang meminta, seperti aplikasi perekaman layar, sedang berjalan (tidak diinstal oleh Play atau dimuat sebelumnya di perangkat).
UNKNOWN_CONTROLLING Aplikasi lain yang dapat digunakan untuk mengontrol perangkat serta input dan output aplikasi yang meminta, seperti aplikasi yang mengontrol dari jarak jauh, sedang berjalan (tidak diinstal oleh Play atau dimuat sebelumnya di perangkat).
UNKNOWN_OVERLAYS Aplikasi lain sedang berjalan (tidak diinstal oleh Play atau dimuat sebelumnya di perangkat) yang mungkin menampilkan overlay pada aplikasi yang meminta.
Kosong (nilai kosong) Risiko akses aplikasi tidak dievaluasi jika persyaratan yang diperlukan tidak terpenuhi. Dalam hal ini, kolom appAccessRiskVerdict kosong. Hal ini dapat terjadi karena beberapa alasan, termasuk:
  • Perangkat tidak cukup tepercaya.
  • Faktor bentuk perangkat bukan ponsel, tablet, atau perangkat foldable.
  • Perangkat tidak menjalankan Android 6 (level API 23) atau yang lebih tinggi.
  • Versi aplikasi yang diinstal di perangkat tidak dikenal oleh Google Play.
  • Versi Google Play Store di perangkat sudah lama.
  • Khusus game: Akun pengguna tidak memiliki lisensi Play untuk game.
  • Permintaan standar digunakan dengan parameter verdictOptOut.
  • Permintaan standar digunakan dengan versi library Play Integrity API yang belum mendukung risiko akses aplikasi untuk permintaan standar.
Verdict Play Protect NO_ISSUES Play Protect diaktifkan dan tidak menemukan masalah aplikasi apa pun di perangkat.
NO_DATA Play Protect diaktifkan, tetapi belum ada pemindaian yang dilakukan. Perangkat atau aplikasi Play Store mungkin baru saja direset.
POSSIBLE_RISK Play Protect dinonaktifkan.
MEDIUM_RISK Play Protect diaktifkan dan telah menemukan bahwa aplikasi yang berpotensi membahayakan terinstal di perangkat.
HIGH_RISK Play Protect diaktifkan dan telah menemukan bahwa aplikasi berbahaya terinstal di perangkat.
UNEVALUATED Verdict Play Protect tidak dievaluasi. Persyaratan yang diperlukan tidak terpenuhi, seperti perangkat tidak cukup tepercaya.

Mengonfigurasi setelan permintaan klasik (opsional)

Lewati bagian ini jika Anda hanya berencana untuk membuat permintaan API standar.

Secara default, Google Play mengelola enkripsi respons, yang berarti backend Anda memanggil server Google untuk mendekripsi hasil. Atau, Anda dapat mengelola kunci sendiri untuk mendekripsi secara lokal dalam lingkungan server yang aman.

Mengizinkan Google mengelola enkripsi respons Anda (direkomendasikan)

Sebaiknya izinkan Google membuat dan mengelola kunci untuk melindungi keamanan aplikasi Anda. Backend Anda akan memanggil server Google Play untuk mendekripsi dan memverifikasi respons.

Mengelola kunci enkripsi Anda sendiri

Untuk mendekripsi secara lokal dalam lingkungan server aman Anda sendiri, Anda dapat mendownload kunci enkripsi dari Konsol Play atau Konsol Play SDK. Aplikasi Anda harus tersedia di Google Play untuk menggunakan fitur ini.

Sebelum mengubah strategi pengelolaan enkripsi respons di Konsol Play, pastikan server Anda dikonfigurasi dengan benar untuk mendekripsi dan memverifikasi token integritas di server Google Play guna menghindari gangguan.

Beralih antara kunci enkripsi yang dikelola Google dan dikelola sendiri

  1. Buka Konsol Play, lalu pilih aplikasi Anda .
  2. Buka Pengujian dan rilis > Integritas aplikasi.
  3. Di samping Play Integrity API, klik Setelan.
  4. Di bagian Permintaan klasik, di samping Enkripsi respons, klik Edit.

Untuk beralih ke kunci yang dikelola sendiri:

  1. Pilih Kelola dan download kunci enkripsi respons saya, lalu upload kunci publik Anda.
  2. Klik Simpan untuk mendownload kunci terenkripsi Anda secara otomatis.
  3. Update server backend aman Anda untuk mendekripsi secara lokal menggunakan kunci ini.

Untuk beralih ke kunci yang dikelola Google:

  1. Pilih Izinkan Google mengelola enkripsi respons saya (direkomendasikan).
  2. Klik Simpan perubahan.
Sebelumnya
Ringkasan
Berikutnya
Buat permintaan standar