Mengintegrasikan Play Integrity untuk PC ke dalam aplikasi Anda

Play Integrity untuk PC membantu Anda memeriksa apakah peristiwa game dan permintaan server berasal dari instance Google Play Game untuk PC yang asli di perangkat PC yang asli. Dengan mendeteksi perangkat yang berpotensi berisiko dan emulator yang tidak dikenal, server backend game Anda dapat merespons dengan tindakan yang sesuai untuk mencegah kecurangan, akses tanpa izin, traffic penipuan, dan penyalahgunaan.

Prasyarat

• Selesaikan penyiapan SDK.
• Tinjau pertimbangan keamanan Integrity API.
• Baca dan pahami persyaratan layanan dan informasi penanganan data Integrity API.
• Di Konsol Google Cloud, buat project Cloud atau pilih project Cloud yang sudah ada dan ingin Anda gunakan dengan Play Integrity untuk PC. Buka APIs & services dan aktifkan Google Play Integrity API.
• Jika Anda memperkirakan akan membuat lebih dari 10 ribu permintaan Play Integrity untuk PC per hari, Anda harus meminta peningkatan jumlah maksimum harian Anda.

Langkah 1: Tentukan cara Anda akan menggunakan Play Integrity untuk PC di game Anda

Tentukan kapan Anda akan memanggil Play Integrity untuk PC guna mendapatkan verdict integritas tentang lingkungan. Misalnya, Anda dapat meminta verdict saat game dibuka, saat pemain login, atau saat pemain bergabung ke game multiplayer. Kemudian tentukan cara Anda akan menangani berbagai respons integritas. Misalnya, Anda dapat:

• Kumpulkan respons tanpa tindakan penegakan apa pun, dan analisis data secara internal untuk memahami apakah respons tersebut merupakan sinyal penyalahgunaan yang berguna.
• Kumpulkan respons dan terapkan logika di server backend Anda untuk mengizinkan perangkat yang lulus verdict integritas memainkan game Anda secara normal, sekaligus menantang atau menolak akses ke traffic yang berasal dari lingkungan yang mencurigakan.
• Kumpulkan respons dan terapkan logika di backend Anda untuk mencocokkan pemain di perangkat yang lulus pemeriksaan integritas, sekaligus mencocokkan traffic yang berasal dari lingkungan yang mencurigakan.

Langkah 2: Minta token integritas di game Anda

Mempersiapkan Play Integrity untuk PC

Siapkan (atau "panaskan") Play Integrity untuk PC, yang 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. Anda dapat melakukannya secara asinkron segera setelah game Anda dibuka sehingga Anda dapat membuat permintaan integritas sesuai permintaan saat diperlukan.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

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 dilakukan evaluasi ulang verdict integritas secara keseluruhan.

Cuplikan kode yang menunjukkan cara memanggil tindakan PrepareIntegrityToken diberikan sebagai berikut:

google::play::integrity::IntegrityClient client_;

google::play::integrity::PrepareIntegrityTokenResult
IntegrityInterface::PrepareIntegrityToken(int64_t cloud_project_number) {
  google::play::integrity::PrepareIntegrityTokenParams params;
  params.cloud_project_number = cloud_project_number;

  auto promise = std::make_shared<
      std::promise<google::play::integrity::PrepareIntegrityTokenResult>>();
  client_.PrepareIntegrityToken(
      params,
      [promise](
          google::play::integrity::PrepareIntegrityTokenResult result) {
        promise->set_value(std::move(result));
      });

  return promise->get_future().get();
}

Meminta token integritas Anda

Token integritas adalah mekanisme bagi game Anda untuk memverifikasi bahwa perangkat tidak dimodifikasi tanpa izin. Setiap kali game Anda membuat permintaan server yang ingin Anda periksa keasliannya, Anda dapat meminta token integritas, lalu mengirimkannya ke server backend game Anda untuk didekripsi dan diverifikasi.

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, Anda 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 untuk PC dapat 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.

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Untuk mengurangi kemungkinan serangan, 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.

Cuplikan kode yang menunjukkan cara memanggil tindakan RequestIntegrityToken disediakan sebagai berikut:

absl::StatusOr<google::play::integrity::RequestIntegrityTokenResult>
IntegrityInterface::RequestIntegrityToken(
    const google::play::integrity::PrepareIntegrityTokenResult&
        prepare_integrity_token_result,
    const std::string& request_hash) {
  // Check if the prepare_integrity_token_result is OK
  if (!prepare_integrity_token_result.ok()) {
    return absl::FailedPreconditionError(
        absl::StrCat("PrepareIntegrityTokenResult is not OK. Error code: ",
                     prepare_integrity_token_result.error_code));
  }

  google::play::integrity::RequestIntegrityTokenParams params{
      .request_token_data =
          prepare_integrity_token_result.request_token_data,
      .request_hash = request_hash};

  auto promise = std::make_shared<std::promise<
      google::play::integrity::RequestIntegrityTokenResult>>();
  client_.RequestIntegrityToken(
      params,
      [promise](google::play::integrity::RequestIntegrityTokenResult result) {
        promise->set_value(std::move(result));
      });

  return promise->get_future().get();
}

Langkah 3: Mendekripsi dan memverifikasi token integritas di server backend game Anda

Mendekripsi token integritas

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:

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. Token integritas yang didekripsi akan terlihat seperti berikut:

{
  "requestDetails": {
    "requestPackageName": "com.your.package.name",
    "requestTime": "2025-08-29T13:10:37.285Z",
    "requestHash": "your_request_hash_string"
  },
  "deviceIntegrity": {
    "deviceRecognitionVerdict": [
      "MEETS_PC_INTEGRITY"
    ]
  },
}

Memverifikasi token integritas

Kolom requestDetails dari token integritas yang didekode berisi informasi tentang permintaan, termasuk informasi yang disediakan developer di requestHash.

Kolom requestHash dan packageName 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, seperti yang ditunjukkan dalam cuplikan kode berikut:

const auto& request_details = json_payload["requestDetails"];

if (request_details.value("requestPackageName", "") != <YOUR_PACKAGE_NAME>) {
  // Don't trust the verdicts.
}

// Check for the existence of the request_hash.
// If you set a request hash in the request and it's not present, you shouldn't
// trust the verdicts.
if (!request_details.contains("requestHash")) {
    // Don't trust the verdicts.
}


// The requestHash from request_details needs to match the request hash your
// app provided.
if (request_details.value("requestHash", "") != <PROVIDED_REQUEST_HASH>) {
    // Don't trust the verdicts.
}

// You can read the rest of payload's fields.

Langkah 4: Tentukan tindakan yang akan diambil berdasarkan verdict integritas

Kolom deviceIntegrity dapat berisi satu nilai, deviceRecognitionVerdict. Anda dapat menggunakan nilai ini untuk menentukan apakah game Anda berjalan di PC yang lulus pemeriksaan integritas Play (yang merupakan respons MEETS_PC_INTEGRITY) atau tidak. Server backend game Anda dapat mengumpulkan informasi ini dan menggunakannya untuk menentukan tindakan yang harus dilakukan game Anda, seperti mengizinkan peristiwa game untuk dilanjutkan atau menolak akses ke traffic berisiko.

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

deviceRecognitionVerdict dapat memiliki nilai berikut:

MEETS_PC_INTEGRITY

Game berjalan di lingkungan PC asli, tempat tidak ada manipulasi di perangkat yang terdeteksi.

Kosong (nilai kosong)

Game berjalan pada perangkat yang memiliki tanda serangan (seperti hooking API) atau penyusupan sistem (seperti perangkat yang menjalankan versi Google Desktop Services yang dimodifikasi), atau aplikasi tidak berjalan pada perangkat fisik (seperti emulator yang tidak lulus pemeriksaan integritas Google Play).

Langkah 5: Tangani kode error

Jika game Anda membuat permintaan Play Integrity untuk PC dan panggilan gagal, game Anda akan menerima kode error. Error ini dapat terjadi karena berbagai alasan, seperti masalah lingkungan seperti koneksi jaringan yang buruk, masalah pada integrasi API, atau aktivitas berbahaya dan serangan aktif.

Kode error yang dapat dicoba lagi

Penyebab error ini terkadang karena kondisi sementara, sehingga Anda harus mencoba lagi panggilan dengan strategi backoff eksponensial.

Lihat di sini untuk rekomendasi lainnya tentang strategi percobaan ulang.

Kode error yang Tidak Dapat Dicoba Lagi

Percobaan ulang otomatis kemungkinan tidak akan membantu dalam kasus ini. Namun, percobaan ulang manual dapat membantu jika pengguna mengatasi kondisi yang menyebabkan masalah tersebut.