Menambahkan Play Integrity API

Play Integrity API untuk PC membantu Anda memeriksa apakah interaksi dan permintaan server berasal dari perangkat PC asli. Dengan mendeteksi interaksi yang berpotensi berisiko dan menipu, server backend aplikasi Anda dapat merespons dengan tindakan yang sesuai untuk mencegah serangan dan mengurangi penyalahgunaan.

API menampilkan verdict yang membantu Anda mendeteksi potensi ancaman, termasuk:

• Perangkat dan lingkungan berisiko: Verdict deviceIntegrity membantu Anda menentukan apakah aplikasi Anda berjalan di perangkat PC asli atau instance asli Google Play Game untuk PC.

Melakukan integrasi dengan API

Untuk mengintegrasikan Play Integrity API untuk PC ke dalam aplikasi, Anda harus melakukan penyiapan awal di Konsol Google Cloud terlebih dahulu. Setelah itu, Anda harus mengikuti langkah-langkah berikut untuk setiap pemeriksaan integritas:

1. Menyiapkan token integritas
2. Meminta token integritas Anda
3. Meminta data token

Penyiapan Awal di Konsol Google Cloud

Setiap aplikasi atau SDK yang memanggil Play Integrity API harus memanfaatkan project Google Cloud untuk mengautentikasi panggilan dan memantau penggunaan API-nya. Jika Anda ingin membuat project Cloud baru atau aplikasi Anda didistribusikan secara eksklusif di luar Google Play, Anda dapat mengaktifkan respons Play Integrity API dari Konsol Google Cloud.

Di Konsol Google Cloud, buat project Cloud baru atau pilih project Cloud yang sudah ada dan ingin Anda gunakan dengan Play Integrity API untuk PC. Buka APIs and services. Pilih enable APIs and services. Cari Play Integrity API, lalu aktifkan. Sekarang Anda dapat mengintegrasikan Play Integrity API ke dalam aplikasi Anda.

Langkah 1: Siapkan token integritas Anda

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

Sebelum meminta token integritas (lihat RequestIntegrityToken), Anda harus menyiapkan (atau "memanaskan") Play Integrity API. Hal ini memungkinkan Google Play meng-cache informasi pengesahan parsial dengan cerdas di perangkat untuk mengurangi latensi di jalur penting saat Anda membuat permintaan untuk verdict integritas.

Jika berhasil, kelanjutan akan dipanggil dengan PrepareIntegrityTokenResultValue yang berisi RequestTokenData yang harus digunakan untuk meminta token integritas. Data ini harus di-cache dalam memori dan digunakan kembali selama durasi sesi aplikasi untuk panggilan ke RequestIntegrityToken. Panggilan ke PrepareIntegrityToken hanya boleh dilakukan jika aplikasi Anda menentukan bahwa perlu untuk mengevaluasi ulang verdict integritas secara keseluruhan.

Langkah 2: Minta token integritas Anda

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Token integritas adalah mekanisme bagi aplikasi Anda untuk memverifikasi bahwa perangkat tidak diubah tanpa izin. Misalnya, server backend Anda dapat menggunakan token integritas untuk memverifikasi:

• Perangkat asli: Menentukan apakah aplikasi Anda berjalan di perangkat asli yang berisi instance asli Google Play Game untuk PC dan tidak dimodifikasi.

Saat memeriksa tindakan pengguna di aplikasi Anda dengan Play Integrity API untuk PC, Anda dapat menggunakan kolom RequestIntegrityTokenParams::request_hash untuk mengurangi serangan modifikasi yang tidak sah. Misalnya, game mungkin ingin melaporkan skor pemain ke server backend game, dan server Anda ingin memverifikasi bahwa skor ini tidak dimodifikasi secara tidak sah oleh server proxy. Play Integrity API menampilkan nilai yang Anda tetapkan dalam kolom ini, di dalam respons integritas yang ditandatangani. Tanpa requestHash, token integritas hanya akan terikat ke perangkat, tetapi tidak ke permintaan tertentu, yang membuka kemungkinan terjadinya serangan.

Untuk memitigasi hal ini saat Anda meminta verdict integritas:

• Hitung ringkasan semua parameter permintaan yang relevan (misalnya SHA256 dari serialisasi permintaan stabil) dari tindakan pengguna atau permintaan server yang terjadi.
• Tetapkan kolom RequestIntegrityTokenParams::request_hash ke digest.

Langkah 3: Minta data token

Setelah Anda meminta verdict integritas, Play Integrity API akan memberikan token respons yang dienkripsi. Untuk mendapatkan verdict integritas perangkat, Anda harus mendekripsi token integritas di server Google. Untuk melakukannya, selesaikan langkah-langkah berikut:

1. Buat akun layanan dalam project Google Cloud yang ditautkan ke aplikasi Anda.

2. Di server aplikasi Anda, ambil token akses dari kredensial akun layanan menggunakan cakupan playintegrity, dan buat permintaan berikut:

   playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
    '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'
   

3. Baca respons JSON.

Payload yang dihasilkan adalah token teks biasa yang berisi verdict dan detail integritas bersama informasi yang disediakan developer. Format token adalah sebagai berikut:

{
  "requestDetails": { ... },
  "deviceIntegrity": { ... },
}

Anda harus memastikan terlebih dahulu bahwa nilai di kolom requestDetails cocok dengan nilai dari permintaan asli sebelum memeriksa setiap verdict integritas. Bagian berikut menjelaskan setiap kolom secara lebih mendetail.

Kolom detail permintaan

Kolom requestDetails berisi informasi tentang permintaan, termasuk informasi yang disediakan developer di requestHash untuk permintaan standar dan nonce untuk permintaan klasik.

"requestDetails": {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the request.
  "requestPackageName": "com.package.name",
  // The timestamp when the integrity token was requested.
  "requestTime": "1675655009345"
  // Request hash provided by the developer.
  "requestHash": "aGVsbG8gd29scmQgdGhlcmU",
}

Nilai ini harus cocok dengan permintaan asal. Oleh karena itu, verifikasi bagian requestDetails payload JSON dengan memastikan bahwa requestPackageName dan requestHash cocok dengan yang dikirim dalam permintaan asli.

Kolom integritas perangkat

Kolom deviceIntegrity dapat berisi satu nilai, deviceRecognitionVerdict, yang memiliki satu atau beberapa label yang merepresentasikan seberapa baik perangkat dapat menerapkan integritas aplikasi. Jika perangkat tidak memenuhi kriteria label apa pun, kolom deviceIntegrity akan menghilangkan deviceRecognitionVerdict.

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

Secara default, deviceRecognitionVerdict dapat berisi hal berikut:

MEETS_PC_INTEGRITY

Menampilkan verdict jika aplikasi berjalan di lingkungan PC asli, yang tidak terdeteksi adanya upaya manipulasi di perangkat.

Kosong (nilai kosong)

Aplikasi berjalan pada 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).

Batas Penggunaan

Batas Penggunaan Play Integrity API

Aplikasi Anda akan tunduk pada jumlah maksimum 10.000 total permintaan per aplikasi per hari. Anda dapat meminta untuk meningkatkan jumlah maksimum harian ini dengan petunjuk berikut jika aplikasi Anda perlu menangani peningkatan jumlah pengguna.

Meningkatkan jumlah maksimum permintaan harian Anda

Agar memenuhi syarat untuk meningkatkan jumlah maksimum permintaan harian, aplikasi Anda harus tersedia di Google Play selain saluran distribusi lainnya.

Untuk meminta peningkatan jumlah maksimum permintaan harian, lakukan hal berikut:

1. Tautkan project Google Cloud yang Anda gunakan untuk Play Integrity API di Konsol Play.
2. Pastikan Anda mengimplementasikan logika API dengan benar, termasuk strategi coba lagi yang direkomendasikan.
3. Minta penambahan kuota menggunakan formulir ini.

Diperlukan waktu hingga satu minggu untuk meningkatkan kuota Play Integrity API. Jadi, sebaiknya Anda memantau penggunaan Play Integrity API di Konsol Google Play atau di Konsol Google Cloud, tempat Anda juga dapat menyiapkan pemberitahuan kuota, untuk menghindari gangguan pada layanan Anda.

Peningkatan kuota akan otomatis diterapkan ke panggilan klien untuk membuat token integritas dan panggilan server untuk mendekripsi dan memverifikasi token integritas.

Pertimbangan keamanan

Play Integrity API memberikan nilai tertinggi untuk aplikasi jika Anda mengikuti praktik yang direkomendasikan berikut:

Memiliki strategi anti-penyalahgunaan

Play Integrity API akan berfungsi optimal jika digunakan bersama sinyal lain sebagai bagian dari keseluruhan strategi anti-penyalahgunaan dan bukan sebagai satu-satunya mekanisme anti-penyalahgunaan. Gunakan API ini bersama praktik terbaik keamanan lainnya yang sesuai untuk aplikasi Anda. Secara default, aplikasi Anda dapat membuat hingga 10.000 total permintaan per hari di semua penginstalan. Anda dapat meminta untuk meningkatkan jumlah maksimum harian.

Mengumpulkan telemetri dan memahami audiens sebelum mengambil tindakan

Sebelum mengubah perilaku aplikasi berdasarkan verdict Play Integrity API, Anda dapat memahami situasi saat ini dengan audiens yang ada dengan menerapkan API tanpa penegakan. Setelah mengetahui verdict yang ditampilkan basis penginstalan Anda saat ini, Anda dapat memperkirakan dampak dari penegakan yang Anda rencanakan, dan menyesuaikan strategi anti-penyalahgunaan dengan tepat.

Meminta verdict integritas pada waktu yang tepat

Anda harus membuat permintaan API sedekat mungkin dengan waktu tindakan atau permintaan server yang ingin Anda pertahankan.

Membuat permintaan API sulit direplikasi

Permintaan API memiliki kolom bernama requestHash yang digunakan untuk melindungi dari modifikasi tidak sah dan serangan serupa. Di kolom ini, Anda harus menyertakan ringkasan semua nilai yang relevan dari permintaan aplikasi Anda. Ikuti panduan tentang cara menggunakan binding konten untuk melindungi permintaan standar aplikasi Anda.

Menghindari menyimpan verdict integritas dalam cache

Menyimpan verdict integritas dalam cache akan meningkatkan risiko proxy, yang merupakan serangan dengan pihak tidak bertanggung jawab yang menggunakan kembali verdict dari perangkat yang baik untuk tujuan penyalahgunaan di lingkungan lain.

Mengirimkan berbagai respons dari server Anda ke aplikasi

Memiliki rentang hasil keputusan lebih sulit untuk direplikasi daripada mengirim respons Izinkan / Tolak biner dari server kembali ke aplikasi untuk setiap respons. Misalnya, Anda dapat menggunakan serangkaian respons terkait seperti Izinkan, Izinkan dengan batas, Izinkan dengan batas setelah penyelesaian CAPTCHA, dan Tolak.

Menampilkan pesan error yang dapat ditindaklanjuti

Jika memungkinkan, berikan pesan error yang berguna kepada pengguna dan beri tahu mereka hal yang dapat dilakukan untuk memperbaikinya.

Membuat rencana untuk masalah atau pemadaman layanan yang tidak terduga

Dasbor status Play menampilkan informasi tentang status layanan Play Integrity API beserta informasi tentang gangguan dan pemadaman layanan. Anda harus merencanakan terlebih dahulu cara kerja server backend jika terjadi pemadaman layanan Play Integrity API berskala besar.

Persyaratan layanan dan keamanan data

Dengan mengakses atau menggunakan Play Integrity API untuk PC, Anda menyetujui Persyaratan Layanan Play Integrity API. Baca dan pahami semua persyaratan dan kebijakan yang berlaku sebelum mengakses API.

Google Play memiliki bagian keamanan data bagi developer untuk mengungkapkan praktik pengumpulan, berbagi, dan keamanan data aplikasi mereka agar pengguna terus mendapatkan informasi. Untuk membantu Anda melengkapi formulir data, lihat informasi tentang cara Play Integrity API menangani data.