Menambahkan Play Integrity ke aplikasi Android

1. Pengantar

Terakhir Diperbarui: 4 Januari 2023

Apa yang dimaksud dengan Play Integrity?

Play Integrity API membantu melindungi aplikasi dan game Anda dari interaksi yang berpotensi berisiko dan bersifat menipu. Anda dapat menggunakan Play Integrity API untuk mendapatkan verdict integritas tentang aplikasi dan perangkat Anda, yang dapat membantu Anda merespons dengan tindakan yang sesuai untuk mengurangi serangan dan penyalahgunaan seperti penipuan, kecurangan, dan akses tidak sah.

Solusi sebelumnya

Play Integrity API menggantikan dua solusi sebelumnya: Library Pemberian Lisensi Aplikasi dan SafetyNet Attestation API. Play Integrity direkomendasikan untuk aplikasi baru. Aplikasi yang sudah ada dan menggunakan solusi sebelumnya harus mempertimbangkan untuk mengupdate agar dapat menggunakan Play Integrity.

Memilih jalur

Play Integrity menyertakan opsi library untuk berbagai jenis aplikasi:

Game atau aplikasi lain yang ditulis dalam C/C++
Aplikasi yang ditulis dalam bahasa pemrograman Kotlin atau Java
Game yang dikembangkan dengan mesin Unity

Codelab ini menyertakan jalur untuk ketiga opsi tersebut. Anda dapat memilih jalur yang relevan dengan kebutuhan pengembangan Anda. Codelab ini melibatkan pembuatan dan deployment server backend. Server ini digunakan bersama di ketiga jenis aplikasi.

Yang akan Anda bangun

Dalam codelab ini, Anda akan mengintegrasikan Play Integrity ke dalam aplikasi contoh dan menggunakan API untuk memeriksa integritas perangkat dan aplikasi. Anda akan men-deploy aplikasi server backend kecil yang digunakan untuk mendukung proses pemeriksaan integritas.

Yang akan Anda pelajari

Cara mengintegrasikan library Play Integrity ke dalam aplikasi
Cara menggunakan Play Integrity API untuk melakukan pemeriksaan integritas
Cara memproses verdict integritas dengan aman menggunakan server
Cara menafsirkan hasil verdict integritas

Codelab ini berfokus pada Play Integrity. Konsep dan blok kode yang tidak-relevan tidak dijelaskan secara mendetail dan disediakan agar Anda cukup menyalin dan menempel.

Yang akan Anda butuhkan

Akun Google dengan pendaftaran Android Developer aktif, akses ke Konsol Play, dan akses ke Konsol Google Cloud.
Untuk jalur C++ atau Kotlin, Android Studio 2021.1.1 atau yang lebih baru.
Untuk jalur Unity, LTS 2020 Unity atau lebih tinggi.
Perangkat berbasis Android yang terhubung ke komputer dan mengaktifkan Opsi developer serta Proses debug USB.

Codelab ini mencakup link ke resource tentang penandatanganan dan upload build ke Konsol Play, tetapi mengasumsikan Anda telah memahami proses ini.

2. Mendapatkan kode

Project codelab tersedia di repo Git. Di direktori induk repo terdapat empat direktori:

Direktori server berisi kode untuk server contoh yang akan Anda deploy.
Direktori cpp berisi project Android Studio untuk menambahkan Play Integrity ke game atau aplikasi C++.
Direktori kotlin berisi project Android Studio untuk menambahkan Play Integrity ke aplikasi Android standar.
Direktori unity berisi project yang dibuat dengan mesin Unity versi LTS 2020 untuk menambahkan Play Integrity ke project Unity.

Dalam setiap direktori contoh klien terdapat dua subdirektori:

Direktori start, yang memiliki versi project yang akan kita modifikasi untuk codelab ini.
Direktori final, yang memiliki versi project yang cocok dengan tampilan project setelah codelab diselesaikan.

Meng-clone repo

Dari command line, ubah ke direktori yang ingin Anda sertakan direktori root add-play-integrity-codelab, lalu clone project dari GitHub menggunakan sintaksis berikut:

git clone https://github.com/android/add-play-integrity-codelab.git

Menambahkan dependensi (khusus C++)

Jika ingin menggunakan jalur C++, Anda perlu menginisialisasi submodul repositori untuk menyiapkan library Dear ImGui yang digunakan untuk antarmuka pengguna. Untuk melakukannya, dari command line:

Ubah direktori kerja menjadi: add-play-integrity-codelab/cpp/start/third-party
git submodule update --init

3. Memahami fungsi klien dan server

Elemen utama model keamanan Play Integrity adalah memindahkan operasi validasi dari perangkat ke server aman yang Anda kontrol. Melakukan operasi ini pada server akan melindunginya dari skenario seperti perangkat yang disusupi, yang mencoba men-deploy serangan replay atau merusak konten pesan.

Server contoh codelab dimaksudkan sebagai contoh, dan untuk tujuan kesederhanaan tidak berisi banyak fitur yang akan diinginkan dalam lingkungan produksi. Daftar nilai yang dihasilkan hanya disimpan dalam memori dan tidak didukung oleh penyimpanan persisten. Endpoint server tidak dikonfigurasi untuk mewajibkan autentikasi.

Endpoint performCommand

Server menyediakan endpoint /performCommand yang diakses melalui permintaan POST HTTP. Isi permintaan diharapkan berupa payload JSON dengan key-value pair berikut:

{
   "commandString": "command-here",
   "tokenString": "token-here"
}

Endpoint /performCommand menampilkan payload JSON dengan key-value pair berikut:

{
   "commandSuccess": true/false,
   "diagnosticMessage": "summary text",
   "expressToken": "token-here"
}

Konten sebenarnya dari parameter commandString tidak berpengaruh. Server memvalidasi integritas commandString saat menggunakan Play Integrity, tetapi tidak menggunakan nilai perintah. Semua versi klien menggunakan nilai "TRANSFER FROM alice TO bob CURRENCY gems QUANTITY 1000".

Nilai parameter tokenString harus salah satu dari:

Token yang dibuat oleh Play Integrity API
Token ekspres yang ditampilkan oleh panggilan sebelumnya yang berhasil ke /performCommand

Server mendekripsi dan memvalidasi token yang disediakan oleh Play Integrity API. Hasil dekripsi adalah payload JSON untuk sinyal integritas. Bergantung pada nilai sinyal, server dapat memilih untuk menyetujui atau menolak perintah. Jika token berhasil didekripsi, deskripsi ringkasan sinyal akan ditampilkan di diagnosticMessage. Biasanya, Anda tidak akan menampilkan informasi ini kepada klien dalam aplikasi produksi, tetapi informasi tersebut digunakan oleh klien codelab untuk menampilkan hasil operasi Anda tanpa harus melihat log server. Jika kondisi error terjadi saat memproses token, error akan ditampilkan di diagnosticMessage.

Pembuatan nonce

Untuk membuat permintaan Play Integrity, Anda perlu membuat nonce dan mengaitkannya dengan permintaan tersebut. Nonce digunakan untuk membantu memastikan permintaan integritas bersifat unik dan hanya diproses satu kali. Nonce juga digunakan untuk memastikan bahwa konten pesan yang terkait dengan permintaan integritas belum dirusak. Untuk mengetahui informasi selengkapnya tentang nonce Play Integrity, lihat dokumentasi.

Dalam codelab ini, nonce dihasilkan dengan menggabungkan dua nilai:

Angka acak 128-bit yang dihasilkan oleh generator angka acak yang aman secara kriptografis
Hash SHA-256 untuk nilai commandString

Play Integrity API mengharapkan nonce menjadi string Base64 tanpa padding yang dienkode URL. Untuk membuat string nonce, codelab ini mengonversi array byte dari angka acak dan nilai hash menjadi string heksadesimal dan menyambungkannya. String yang dihasilkan adalah string Base64 yang valid, tetapi tidak dienkode atau didekodekan.

Klien codelab mengambil angka acak dengan memanggil endpoint /getRandom di server dengan permintaan GET HTTP. Ini adalah metode pembuatan acak yang paling aman, karena server dapat memverifikasi bahwa kode tersebut merupakan sumber angka acak yang digunakan dalam permintaan perintah. Namun, tindakan ini melibatkan perjalanan bolak-balik tambahan ke server. Klien dapat menghilangkan perjalanan bolak-balik ini dengan menghasilkan angka acak sendiri, dengan beberapa kompromi terhadap keamanan.

Token Ekspres

Karena memanggil PIA itu mahal, server juga menyediakan token ekspres, metode alternatif untuk autentikasi yang memberikan keamanan yang lebih rendah dengan biaya yang lebih rendah. Token ekspres ditampilkan di kolom expressToken oleh panggilan yang berhasil ke /serverCommand dengan pemeriksaan integritas yang lulus. Memanggil Play Integrity API secara komputasi mahal dan dimaksudkan untuk melindungi operasi bernilai tinggi. Dengan menampilkan token ekspres, server menyediakan autentikasi dengan keamanan lebih rendah untuk melakukan operasi yang mungkin kurang penting atau terjadi terlalu sering untuk membenarkan validasi penuh dengan Play Integrity API. Token ekspres dapat digunakan sebagai ganti token Play Integrity saat memanggil /serverCommand. Setiap token ekspres digunakan satu kali. Panggilan yang berhasil ke /serverCommand menggunakan token ekspres yang valid akan menampilkan token ekspres baru.

Dalam implementasi codelab, karena token ekspres dibuat secara unik di server, perintahnya masih terlindungi dari serangan replay. Namun, token ekspres kurang aman, karena menghilangkan perlindungan hashing terhadap modifikasi perintah dan tidak dapat mendeteksi modifikasi perangkat yang terjadi setelah panggilan awal ke Play Integrity API.

Arsitektur server Codelab

Untuk codelab ini, Anda dapat membuat instance server dengan menggunakan program server contoh yang disertakan dan ditulis dalam Kotlin menggunakan framework Ktor. Project ini menyertakan file konfigurasi untuk men-deploy-nya ke App Engine Google Cloud. Petunjuk dalam codelab ini mencakup pembuatan dan deployment ke App Engine. Jika Anda menggunakan penyedia cloud lain, Ktor memiliki petunjuk deployment untuk beberapa layanan cloud. Anda dapat memodifikasi project sesuai kebutuhan dan men-deploy-nya ke layanan pilihan Anda. Men-deploy ke instance server lokal Anda sendiri adalah opsi tambahan.

Penggunaan kode contoh untuk server tidak diperlukan. Jika memiliki framework aplikasi web pilihan, Anda dapat mengimplementasikan endpoint /getRandom dan /performCommand dalam framework Anda sendiri menggunakan server contoh codelab sebagai panduan.

Desain klien

Ketiga versi klien, yaitu mesin C++, Kotlin, dan Unity, menyajikan antarmuka pengguna yang serupa.

Tombol Request random memanggil endpoint /getRandom di server. Hasilnya ditampilkan dalam kolom teks. Hasil ini dapat digunakan untuk memverifikasi koneksi dan fungsi server sebelum Anda menambahkan integrasi Play Integrity.

Tombol Call server with integrity check tidak melakukan apa pun di awal codelab. Anda akan mengikuti langkah-langkah untuk menambahkan kode operasi berikut:

Panggil /getRandom untuk mendapatkan angka acak
Buat nonce
Buat permintaan Play Integrity menggunakan nonce
Panggil /performCommand menggunakan token yang dibuat oleh permintaan Play Integrity
Tampilkan hasil /performCommand

Hasil perintah ditampilkan di kolom teks. Untuk perintah yang berhasil, ini adalah ringkasan informasi verdict perangkat yang ditampilkan oleh pemeriksaan Play Integrity.

Tombol Call server with express token akan muncul setelah operasi Call server with integrity check berhasil. Fungsi ini memanggil /performCommand menggunakan token ekspres dari /performCommand sebelumnya. Kolom teks digunakan untuk menampilkan keberhasilan atau kegagalan perintah. Nilai token ekspres yang ditunjukkan akan ditampilkan di kolom teks yang digunakan untuk angka acak.

Fungsi Play Integrity API yang melaporkan error melakukannya dengan menampilkan kode error. Untuk mengetahui detail selengkapnya tentang kode error ini, lihat dokumentasi Play Integrity. Beberapa error mungkin disebabkan oleh kondisi lingkungan, seperti koneksi internet yang tidak stabil atau perangkat yang kelebihan beban. Untuk error semacam ini, pertimbangkan untuk menyertakan opsi coba lagi dengan backoff eksponensial. Dalam codelab ini, error Play Integrity akan dicetak ke dalam Logcat.

4. Menyiapkan Google Cloud App Engine

Untuk menggunakan Google Cloud, lakukan langkah-langkah berikut:

Daftar ke Google Cloud Platform. Gunakan Akun Google yang sama dengan yang didaftarkan ke Konsol Play.
Buat akun penagihan.
Instal dan lakukan inisialisasi Google Cloud SDK.

Gunakan Google Cloud CLI yang baru diinstal untuk menjalankan perintah berikut:

Instal ekstensi App Engine untuk Java: gcloud components install app-engine-java
Buat project Cloud baru, yang menggantikan $yourname di perintah berikut dengan beberapa ID unik: gcloud projects create $yourprojectname --set-as-default
Buat aplikasi App Engine di project Cloud: gcloud app create

5. Men-deploy server

Menetapkan nama paket aplikasi

Pada langkah ini, Anda akan menambahkan nama paket aplikasi ke kode server. Di editor teks, buka file sumber ValidateCommand.kt. File ini berada di direktori berikut:

add-play-integrity-codelab/server/src/main/kotlin/com/google/play/integrity/codelab/server/util

Cari baris berikut dan ganti teks placeholder dengan ID paket yang unik, lalu simpan file tersebut:

const val APPLICATION_PACKAGE_IDENTIFIER = "com.your.app.package"

Anda akan menetapkan ID ini nanti di project klien sebelum mengupload aplikasi ke Konsol Play.

Membangun server dan men-deploy ke App Engine

Gunakan Google Cloud CLI untuk menjalankan perintah berikut dari direktori add-play-integrity/server guna mem-build dan men-deploy server:

Di Linux atau macOS:

./gradlew appengineDeploy

Di Microsoft Windows:

gradlew.bat appengineDeploy

Catat lokasi Layanan yang di-deploy di output dari deployment yang berhasil. Anda memerlukan URL ini untuk mengonfigurasi klien agar dapat berkomunikasi dengan server.

Memverifikasi deployment

Anda dapat menggunakan Google Cloud CLI untuk menjalankan perintah berikut guna memastikan server berfungsi dengan benar:

gcloud app browse

Perintah ini akan membuka browser web dan membuka URL root. Server contoh akan menampilkan pesan Halo Dunia! saat diakses dari URL root.

6. Mengonfigurasi aplikasi di Konsol Play

Mengonfigurasi Integritas Aplikasi di Konsol Play

Jika sudah memiliki entri aplikasi di Konsol Play, Anda dapat menggunakannya untuk codelab ini. Atau, ikuti langkah-langkah untuk membuat aplikasi baru di Konsol Play. Setelah memilih atau membuat aplikasi di Konsol Play, Anda perlu mengonfigurasi Integritas Aplikasi. Dari menu sebelah kiri Konsol Play, buka Integritas aplikasi di bagian Rilis.

Membuat dan menautkan project Google Cloud

Klik tombol Tautkan project Cloud. Pilih project Google Cloud yang Anda gunakan dengan server, lalu klik tombol Tautkan project.

Akses Google Cloud untuk server Anda

Server backend Anda harus mendekripsi token integritas yang dihasilkan di klien oleh Play Integrity API. Play Integrity menawarkan dua pilihan untuk pengelolaan kunci: Kunci yang dibuat dan dikelola oleh Google atau kunci yang disediakan oleh developer. Codelab ini menggunakan perilaku default yang direkomendasikan untuk kunci yang dikelola Google.

Dengan kunci yang dikelola Google, server backend Anda meneruskan token integritas yang dienkripsi ke server Google Play untuk didekripsi. Server codelab menggunakan Library Klien Google API untuk melakukan komunikasi dengan server Google Play.

Setelah server aktif dan berjalan, dan Anda telah mengonfigurasi aplikasi di Konsol Play, Anda dapat mulai menyesuaikan satu atau beberapa klien sesuai dengan platform yang Anda pilih. Semua langkah untuk platform tertentu dikelompokkan bersama, sehingga Anda dapat mengabaikan petunjuk untuk platform yang tidak Anda gunakan.

7. Membangun dan menjalankan klien (C++)

Jalankan Android Studio. Dari jendela Welcome to Android Studio, klik tombol Open dan buka project Android Studio yang berada di add-play-integrity-codelab/cpp/start.

Memperbarui ID aplikasi

Sebelum mengupload build ke Google Play, Anda perlu mengubah ID aplikasi dari default ke sesuatu yang unik. Lakukan langkah-langkah berikut:

Dari panel Project di Android Studio, temukan file build.gradle di start/app dan buka file tersebut.
Temukan pernyataan applicationId.
Ubah com.google.play.integrity.codelab.cpp menjadi nama paket yang Anda pilih saat men-deploy server, lalu simpan file tersebut.
Di bagian atas file, banner akan muncul dan menginformasikan bahwa file Gradle telah berubah. Klik Sync Now untuk memuat ulang dan menyinkronkan ulang file.
Dari panel Project di Android Studio, buka file AndroidManifest.xml di bagian start/app/src/main.
Temukan pernyataan package="com.example.google.codelab.playintegritycpp".
Ganti com.example.google.codelab.playintegritycpp dengan nama paket Anda yang unik, lalu simpan file.
Dari panel Project di Android Studio, buka file PlayIntegrityCodelabActivity di bagian start/app/src/main/java/com.example.google.codelab.playintegritycpp.
Temukan pernyataan package com.example.google.codelab.playintegritycpp.
Ganti com.example.google.codelab.playintegritycpp dengan nama paket Anda yang unik.
Klik kanan nama paket baru, lalu pilih Show Context Actions.
Pilih Move to (nama paket baru Anda).
Jika ada, pilih tombol Sync Now di bagian atas file.

Memperbarui URL server

Project tersebut perlu diperbarui agar mengarah ke lokasi URL tempat Anda men-deploy server.

Dari panel Project di Android Studio, buka file server_urls.hpp di bagian start/app/src/main/cpp.
Tambahkan URL root yang ditampilkan saat Anda men-deploy server ke definisi GET_RANDOM_URL dan PERFORM_COMMAND_URL, lalu simpan file tersebut.

Hasilnya akan terlihat seperti:

constexpr char GET_RANDOM_URL[] = "https://your-play-integrity-server.uc.r.appspot.com/getRandom";
constexpr char PERFORM_COMMAND_URL[] = "https://your-play-integrity-server.uc.r.appspot.com/performCommand";

URL spesifik akan bervariasi, bergantung pada nama project dan region Google Cloud yang Anda gunakan untuk men-deploy server.

Membangun dan menjalankan

Menghubungkan perangkat Android yang dikonfigurasi untuk pengembangan. Di Android Studio, build project dan jalankan di perangkat yang terhubung. Aplikasi akan muncul seperti berikut:

Sentuh tombol Request Random untuk mengeksekusi kode yang membuat permintaan HTTP ke server Anda untuk meminta angka acak. Setelah penundaan singkat, Anda akan melihat angka acak di layar:

Jika pesan error ditampilkan, output panel Logcat mungkin berisi detail selengkapnya.

Setelah memastikan Anda berkomunikasi dengan server melalui keberhasilan dalam mengambil nilai acak, Anda siap untuk mulai mengintegrasikan Play Integrity API.

8. Menambahkan Play Integrity ke project (C++)

Mendownload SDK

Anda harus mendownload dan mengekstrak Play Core SDK. Lakukan langkah-langkah berikut:

Download Play Core SDK yang dikemas dalam file .zip dari halaman Play Core Native SDK.
Ekstrak file ZIP.
Pastikan direktori yang baru diekstrak diberi nama play-core-native-sdk, lalu salin atau pindahkan ke direktori add-play-integrity-codelab/cpp/start.

Mengupdate build.gradle

Di Android Studio, dari panel Project, buka file build.gradle tingkat modul di direktori start/app.

Tambahkan baris berikut di bawah baris apply plugin: 'com.android.application':

def playcoreDir = file("../play-core-native-sdk")

Temukan blok externalNativeBuild di blok defaultConfig dan ubah pernyataan arguments di dalam blok cmake agar cocok dengan yang berikut:

                arguments "-DANDROID_STL=c++_shared",
                          "-DPLAYCORE_LOCATION=$playcoreDir"

Tambahkan item berikut di dalam blok android di bagian akhir:

    buildTypes {
        release {
            proguardFiles getDefaultProguardFile("proguard-android.txt"),
                          "proguard-rules.pro",
                          "$playcoreDir/proguard/common.pgcfg",
                          "$playcoreDir/proguard/integrity.pgcfg"
        }
    }

Tambahkan baris ini di dalam blok dependencies di bagian akhir:

    implementation files("$playcoreDir/playcore.aar")

Simpan perubahan. Di bagian atas file, banner akan muncul dan menginformasikan bahwa file Gradle telah berubah. Klik Sync Now untuk memuat ulang dan menyinkronkan ulang file.

Memperbarui CMakeList.txt

Di Android Studio, dari panel Project, buka file CMakeLists.txt di direktori start/app/src/main/cpp.

Tambahkan baris berikut di bawah perintah find_package:

include("${PLAYCORE_LOCATION}/playcore.cmake")
add_playcore_static_library()

Temukan baris target_include_directories(game PRIVATE dan tambahkan baris berikut di bawahnya:

        ${PLAYCORE_LOCATION}/include

Temukan baris target_link_libraries(game dan tambahkan baris berikut di bawahnya:

        playcore

Simpan file tersebut. Di bagian atas file, banner akan muncul dan menginformasikan bahwa file build eksternal telah berubah. Klik Sync Now untuk memuat ulang dan menyinkronkan ulang file.

Pilih Make Project dari menu Build, dan pastikan project berhasil dibuat.

9. Membuat permintaan integritas (C++)

Aplikasi Anda memperoleh informasi integritas dengan menggunakan Play Integrity API untuk meminta token, yang kemudian Anda kirim ke server untuk didekripsi dan diverifikasi. Sekarang, Anda akan menambahkan kode ke project untuk melakukan inisialisasi Play Integrity API dan menggunakannya untuk membuat permintaan integritas.

Menambahkan tombol perintah

Dalam aplikasi atau game dunia nyata, Anda dapat melakukan pemeriksaan integritas sebelum aktivitas tertentu, seperti melakukan pembelian di toko atau bergabung ke sesi game multiplayer. Dalam codelab ini, kami akan menambahkan tombol ke UI untuk memicu pemeriksaan integritas secara manual dan memanggil server, dengan meneruskan token Play Integrity yang dihasilkan.

Project codelab berisi class ClientManager, yang ditentukan dalam file sumber client_manager.cpp dan client_manager.hpp. Untuk memudahkan, file ini telah ditambahkan ke project, tetapi tidak memiliki kode implementasi yang kini akan Anda tambahkan.

Untuk menambahkan tombol UI, mulai dengan membuka file demo_scene.cpp dari panel Project Android Studio, di direktori start/app/src/main/cpp. Pertama, cari fungsi DemoScene::GenerateCommandIntegrity() yang kosong dan tambahkan kode berikut:

    const auto commandResult =
            NativeEngine::GetInstance()->GetClientManager()->GetOperationResult();
    if (commandResult != ClientManager::SERVER_OPERATION_PENDING) {
        if (ImGui::Button("Call server with integrity check")) {
            DoCommandIntegrity();
        }
    }

Selanjutnya, cari fungsi DemoScene::DoCommandIntegrity() yang kosong. Tambahkan kode berikut.

    ClientManager *clientManager = NativeEngine::GetInstance()->GetClientManager();
    clientManager->StartCommandIntegrity();
    mServerRandom = clientManager->GetCurrentRandomString();

Simpan file tersebut. Anda kini akan mengupdate class ClientManager contoh untuk menambahkan fungsi Play Integrity yang sebenarnya.

Memperbarui file header pengelola

Buka file client_manager.hpp dari panel Project Android Studio, di direktori start/app/src/main/cpp.

Sertakan file header untuk Play Integrity API dengan menambahkan baris berikut di bawah baris #include "util.hpp":

#include "play/integrity.h"

Class ClientManager harus menyimpan referensi ke objek IntegrityTokenRequest dan IntegrityTokenResponse. Tambahkan baris berikut ke bagian bawah definisi class ClientManager:

    IntegrityTokenRequest *mTokenRequest;
    IntegrityTokenResponse *mTokenResponse;

Simpan file tersebut.

Melakukan inisialisasi dan menonaktifkan Play Integrity

Dari panel Project Android Studio, buka file client_manager.cpp di direktori start/app/src/main/cpp.

Temukan konstruktor ClientManager::ClientManager(). Ganti pernyataan mInitialized = false; dengan kode berikut:

    mTokenRequest = nullptr;
    mTokenResponse = nullptr;

    const android_app *app = NativeEngine::GetInstance()->GetAndroidApp();
    const IntegrityErrorCode errorCode = IntegrityManager_init(app->activity->vm,
                                                               app->activity->javaGameActivity);
    if (errorCode == INTEGRITY_NO_ERROR) {
        mInitialized = true;
    } else {
        mInitialized = false;
        ALOGE("Play Integrity initialization failed with error: %d", errorCode);
        ALOGE("Fatal Error: Play Integrity is unavailable and cannot be used.");
    }

Tambahkan kode berikut ke destruktor ClientManager::~ClientManager():

    if (mInitialized) {
        IntegrityManager_destroy();
        mInitialized = false;
    }

Meminta token integritas

Meminta token integritas dari Play Integrity API adalah operasi asinkron. Anda harus membuat objek permintaan token, menetapkan nilai nonce ke objek tersebut, dan membuat permintaan token. Untuk melakukannya, tambahkan kode berikut ke fungsi ClientManager::StartCommandIntegrity() yang kosong:

    // Only one request can be in-flight at a time
    if (mStatus != CLIENT_MANAGER_REQUEST_TOKEN) {
        mResult = SERVER_OPERATION_PENDING;
        // Request a fresh random
        RequestRandom();
        if (mValidRandom) {
            GenerateNonce();
            IntegrityTokenRequest_create(&mTokenRequest);
            IntegrityTokenRequest_setNonce(mTokenRequest, mCurrentNonce.c_str());

            const IntegrityErrorCode errorCode =
                    IntegrityManager_requestIntegrityToken(mTokenRequest, &mTokenResponse);
            if (errorCode != INTEGRITY_NO_ERROR) {
                // Log the error, in a real application, for potentially
                // transient errors such as network connectivity, you should
                // add retry with an exponential backoff
                ALOGE("Play Integrity returned error: %d", errorCode);
                CleanupRequest();
                mStatus = CLIENT_MANAGER_IDLE;
            } else {
                mStatus = CLIENT_MANAGER_REQUEST_TOKEN;
            }
        }
    }

Karena permintaan token beroperasi secara asinkron, Anda harus memeriksa penyelesaiannya. Class ClientManager memiliki fungsi Update() yang dipanggil sebagai bagian dari loop update aplikasi. Tambahkan kode berikut ke fungsi ClientManager::Update() untuk memeriksa status permintaan token, dan proses hasilnya setelah selesai:

    if (mStatus == CLIENT_MANAGER_REQUEST_TOKEN) {
        IntegrityResponseStatus responseStatus = INTEGRITY_RESPONSE_UNKNOWN;
        const IntegrityErrorCode errorCode =
                IntegrityTokenResponse_getStatus(mTokenResponse, &responseStatus);
        if (errorCode != INTEGRITY_NO_ERROR) {
            // Log the error, in a real application, for potentially
            // transient errors such as network connectivity, you should
            // add retry with an exponential backoff
            ALOGE("Play Integrity returned error: %d", errorCode);
            CleanupRequest();
            mStatus = CLIENT_MANAGER_IDLE;
        } else if (responseStatus == INTEGRITY_RESPONSE_COMPLETED) {
            std::string tokenString = IntegrityTokenResponse_getToken(mTokenResponse);
            SendCommandToServer(tokenString);
            CleanupRequest();
            mStatus = CLIENT_MANAGER_RESPONSE_AVAILABLE;
        }
    }

Membersihkan objek permintaan

Anda harus memberi tahu Play Integrity API jika sudah selesai dengan objek respons dan permintaan token, sehingga API tersebut dapat menghancurkannya dan mengklaim kembali resource-nya. Tambahkan kode berikut ke fungsi ClientManager::CleanupRequest():

    if (mTokenResponse != nullptr) {
        IntegrityTokenResponse_destroy(mTokenResponse);
        mTokenResponse = nullptr;
    }
    if (mTokenRequest != nullptr) {
        IntegrityTokenRequest_destroy(mTokenRequest);
        mTokenRequest = nullptr;
    }

Pilih Make Project dari menu Build dan pastikan project berhasil dibuat.

10. Mengirim token ke server (C++)

Selanjutnya, Anda akan menambahkan kode untuk mengirimkan perintah ke server yang menyertakan token integritas. Anda juga akan menambahkan kode untuk memproses hasilnya.

Tambahkan kode berikut ke fungsi ClientManager::SendCommandToServer():

// Note that for simplicity, we are doing HTTP operations as
// synchronous blocking instead of managing them from a
// separate network thread
HTTPClient client;
std::string errorString;

// Manually construct the json payload for ServerCommand
std::string payloadString = COMMAND_JSON_PREFIX;
payloadString += TEST_COMMAND;
payloadString += COMMAND_JSON_TOKEN;
payloadString += token;
payloadString += COMMAND_JSON_SUFFIX;

auto result = client.Post(PERFORM_COMMAND_URL, payloadString, &errorString);
if (!result) {
   ALOGE("SendCommandToServer Curl reported error: %s", errorString.c_str());
   mResult = SERVER_OPERATION_NETWORK_ERROR;
} else {
   ALOGI("SendCommandToServer result: %s", (*result).c_str())
   // Preset to success, ParseResult will set a failure result if the parsing
   // errors.
   mResult = SERVER_OPERATION_SUCCESS;
   ParseResult(*result);
}

Tambahkan kode berikut ke fungsi ClientManager::ParseResult():

    bool validJson = false;
    JsonLookup jsonLookup;
    if (jsonLookup.ParseJson(resultJson)) {
        // Look for all of our needed fields in the returned json
        auto commandSuccess = jsonLookup.GetBoolValueForKey(COMMANDSUCCESS_KEY);
        if (commandSuccess) {
            auto diagnosticString = jsonLookup.GetStringValueForKey(DIAGNOSTICMESSAGE_KEY);
            if (diagnosticString) {
                auto expressString = jsonLookup.GetStringValueForKey(EXPRESSTOKEN_KEY);
                if (expressString) {
                    if (*commandSuccess) {
                        // Express token only valid if the server reports the command succeeded
                        mValidExpressToken = true;
                    } else {
                        mValidExpressToken = false;
                        mResult = SERVER_OPERATION_REJECTED_VERDICT;
                    }
                    mCurrentSummary = *diagnosticString;
                    mCurrentExpressToken = *expressString;
                    validJson = true;
                }
            }
        }
    }
    if (!validJson) {
        mResult = SERVER_OPERATION_INVALID_RESULT;
    }

Anda kini akan membuat app bundle yang ditandatangani dan menguploadnya ke Konsol Play untuk menguji aplikasi tersebut.

11. Membangun dan mengupload (C++)

Membuat dan menyiapkan keystore untuk aplikasi

Android mewajibkan semua aplikasi ditandatangani secara digital dengan sertifikat sebelum diinstal atau diupdate di perangkat.

Kita akan membuat Keystore untuk aplikasi di codelab ini. Jika Anda memublikasikan update untuk game yang sudah ada, gunakan kembali Keystore yang sama seperti yang Anda gunakan untuk merilis versi aplikasi sebelumnya.

Membuat keystore dan membangun App Bundle rilis

Ikuti langkah-langkah di Keystore dengan Android Studio untuk membuat keystore, lalu gunakan untuk menghasilkan build rilis game yang ditandatangani. Di Android Studio, pilih Generate Signed Bundle/APK dari menu Build untuk memulai proses build. Pilih opsi App Bundle saat diminta untuk memilih Android App Bundle atau APK. Pada akhir proses, Anda akan memiliki file .aab yang sesuai untuk diupload ke Konsol Google Play.

Mengupload ke Konsol Play

Setelah membuat file App Bundle, upload ke Konsol Play. Sebaiknya gunakan jalur pengujian internal untuk memfasilitasi akses ke build Anda dengan cepat.

Menjalankan build pengujian

Sekarang Anda harus mendownload dan menjalankan build pengujian dari Play Store. Untuk saat ini, ada kode sukses placeholder dalam fungsi yang akan mengirim token integritas ke server Anda, sehingga proses memulai pemeriksaan integritas akan berhasil dan menghasilkan tampilan berikut:

Selamat, Anda telah mengintegrasikan Play Integrity ke dalam aplikasi C++. Lanjutkan ke contoh klien lainnya, atau langsung ke bagian akhir codelab ini.

12. Membangun dan menjalankan klien (Unity)

Project Unity codelab dibuat menggunakan LTS 2020 Unity (2020.3.31f1), tetapi harus kompatibel dengan versi Unity yang lebih tinggi. Plugin Play Integrity untuk Unity kompatibel dengan LTS 2018 Unity dan yang lebih tinggi.

Penyiapan project

Lakukan langkah-langkah berikut:

Dari Unity Hub atau Unity Editor, buka project Unity yang berada di add-play-integrity-codelab/unity/start.
Setelah project dimuat, pilih Build Settings... dari menu File Unity.
Di jendela Build Settings, ubah platform ke Android.
Di jendela Build Settings, klik tombol Player Settings....
Di jendela Project Settings, dengan kategori Player dipilih, temukan bagian Settings for Android. Luaskan daftar Other Settings.

Temukan entri Package Name di bagian Identification.

Ubah nama paket ke ID yang Anda pilih saat men-deploy server.
Tutup jendela Project Settings.
Pilih Save Project dari menu File Unity.

Memperbarui URL server

Project tersebut perlu diperbarui agar mengarah ke lokasi URL tempat Anda men-deploy server. Caranya, lakukan langkah-langkah berikut:

Buka file PlayIntegrityController.cs dari folder Scripts di IDE atau editor teks.
Ubah nilai variabel URL_GETRANDOM dan URL_PERFORMCOMMAND agar mengarah ke server Anda.
Simpan file tersebut.

Hasilnya akan terlihat seperti:

    private readonly string URL_GETRANDOM = "https://your-play-integrity-server.uc.r.appspot.com/getRandom";
    private readonly string URL_PERFORMCOMMAND = "https://your-play-integrity-server.uc.r.appspot.com/performCommand";

URL spesifik akan bervariasi, bergantung pada nama project dan region Google Cloud yang Anda gunakan untuk men-deploy server.

Menguji fungsi server

Anda dapat menguji fungsi server dengan menjalankan project di editor Unity. Lakukan langkah-langkah berikut:

Buka file scene SampleScene yang berada di folder Scenes.
Klik tombol Play di editor.
Klik tombol Request Random di tampilan Game.

Setelah penundaan singkat, nilai acak akan ditampilkan di layar, yang akan terlihat seperti berikut:

13. Menambahkan plugin Play Integrity ke project (Unity)

Mendownload plugin

Di browser web, buka halaman rilis untuk repositori GitHub Plugin Unity Play. Gunakan rilis plugin terbaru. Download com.google.play.integrity-<version>.File unitypackage untuk Play Integrity dalam daftar Assets.

Menginstal plugin

Dari panel menu editor Unity, pilih Assets -> Import Package -> Custom Package..., lalu buka file .unitypackage yang telah Anda download. Klik tombol Import setelah jendela Import Unity Package muncul.

Plugin ini mencakup External Dependency Manager untuk Unity (EDM4U). EDM4U menerapkan resolusi dependensi otomatis untuk komponen Java yang diperlukan untuk menggunakan Play Integrity. Saat diminta untuk mengaktifkan resolusi dependensi otomatis, klik tombol Enable.

Sebaiknya gunakan resolusi otomatis. Masalah dependensi dapat mengakibatkan project Anda gagal dibangun atau dijalankan.

14. Membuat permintaan integritas (Unity)

Membuat permintaan integritas

Untuk membuat permintaan integritas, lakukan langkah-langkah berikut.

Buka file PlayIntegrityController.cs dari folder Scripts di IDE atau editor teks.
Tambahkan baris berikut ke blok pernyataan using di bagian atas file:

using Google.Play.Integrity;

Cari fungsi RunIntegrityCommand() dan ganti pernyataan yield return null; dengan kode berikut:

        // Call our server to retrieve a random number.
        yield return GetRandomRequest();
        if (!string.IsNullOrEmpty(_randomString))
        {
            // Create an instance of an integrity manager.
            var integrityManager = new IntegrityManager();

            // Request the integrity token by providing a nonce.
            var tokenRequest = new IntegrityTokenRequest(GenerateNonceString(_randomString,
                TEST_COMMAND));
            var requestIntegrityTokenOperation =
                integrityManager.RequestIntegrityToken(tokenRequest);

            // Wait for PlayAsyncOperation to complete.
            yield return requestIntegrityTokenOperation;

            // Check the resulting error code.
            if (requestIntegrityTokenOperation.Error != IntegrityErrorCode.NoError)
            {
                // Log the error, in a real application, for potentially
                // transient errors such as network connectivity, you should
                // add retry with an exponential backoff
                Debug.Log($@"IntegrityAsyncOperation failed with error: 
                    {requestIntegrityTokenOperation.Error.ToString()}");
                yield break;
            }

            // Get the response.
            var tokenResponse = requestIntegrityTokenOperation.GetResult();

            // Send the command to our server with a POST request, including the
            // token, which will be decrypted and verified on the server.
            yield return PostServerCommand(tokenResponse.Token);
        }

Mengirim perintah ke server

Lanjutkan mengedit file PlayIntegrityController.cs dengan menemukan fungsi PostServerCommand() dan mengganti pernyataan yield return null; dengan kode berikut:

        // Start a HTTP POST request to the performCommand URL, sending it the
        // command and integrity token data provided by Play Integrity.
        var serverCommand = new ServerCommand(TEST_COMMAND, tokenResponse);
        var commandRequest = new UnityWebRequest(URL_PERFORMCOMMAND, "POST");
        string commandJson = JsonUtility.ToJson(serverCommand);
        byte[] jsonBuffer = Encoding.UTF8.GetBytes(commandJson);
        commandRequest.uploadHandler = new UploadHandlerRaw(jsonBuffer);
        commandRequest.downloadHandler = new DownloadHandlerBuffer();
        commandRequest.SetRequestHeader(CONTENT_TYPE, JSON_CONTENT);
        yield return commandRequest.SendWebRequest();

        if (commandRequest.result == UnityWebRequest.Result.Success)
        {
            // Parse the command result Json
            var commandResult = JsonUtility.FromJson<CommandResult>(
                commandRequest.downloadHandler.text);
            if (commandResult != null)
            {
                resultLabel.text = commandResult.diagnosticMessage;
                _expressToken = commandResult.expressToken;
                if (commandResult.commandSuccess)
                {
                    resultLabel.color = Color.green;
                    expressButton.SetActive(true);
                }
                else
                {
                    resultLabel.color = Color.black;
                    expressButton.SetActive(false);
                }
            }
            else
            {
                Debug.Log("Invalid CommandResult json");
            }
        }
        else
        {
            Debug.Log($"Web request error on processToken: {commandRequest.error}");
        }

Simpan file tersebut.

15. Membangun dan mengupload (Unity)

Gunakan editor Unity Android Keystore Manager untuk mengonfigurasi build Anda agar ditandatangani untuk diupload ke Konsol Play.

Setelah mengonfigurasi informasi penandatanganan, lakukan langkah-langkah berikut:

Pilih Build -> Build Settings... dari menu File Unity.
Pastikan SampleScene disertakan dalam daftar Scenes in Build.
Pastikan kotak Build App Bundle (Google Play) dicentang.
Klik tombol Build, lalu beri nama file ekspor.

Setelah membuat file App Bundle, upload ke Konsol Play. Sebaiknya gunakan jalur pengujian internal untuk memfasilitasi akses ke build Anda dengan cepat.

Kini Anda dapat mendownload dan menginstal build untuk menjalankan pemeriksaan integritas. Hasilnya akan terlihat seperti berikut:

Selamat, Anda telah mengintegrasikan Play Integrity ke project mesin Unity. Lanjutkan ke contoh klien lainnya, atau langsung ke bagian akhir codelab ini.

16. Membangun dan menjalankan project (Kotlin)

Jalankan Android Studio. Dari jendela Welcome to Android Studio, klik tombol Open dan buka project Android Studio yang berada di add-play-integrity-codelab/kotlin/start.

Memperbarui ID aplikasi

Sebelum mengupload build ke Google Play, Anda perlu mengubah ID aplikasi dari default ke sesuatu yang unik. Lakukan langkah-langkah berikut:

Dari panel Project di Android Studio, buka file build.gradle untuk modul PlayIntegrityCodelab.app.
Temukan pernyataan applicationId.
Ubah com.example.google.codelab.playintegritykotlin ke ID yang Anda pilih saat men-deploy server dan menyimpan file.
Di bagian atas file, banner akan muncul dan menginformasikan bahwa file Gradle telah berubah. Klik Sync Now untuk memuat ulang dan menyinkronkan ulang file.

Memperbarui URL server

Project tersebut perlu diupdate agar mengarah ke lokasi URL tempat Anda men-deploy server. Caranya, lakukan langkah-langkah berikut:

Dari panel Project di Android Studio, buka file IntegrityServer di bagian start/app/src/main/java/com.example.google.codelab.playintegritykotlin/integrity.
Ubah URL dari ‘https://your.play-integrity.server.com' menjadi URL dasar server Anda, lalu simpan file.

Hasilnya akan terlihat seperti:

    private val SERVER_URL: String = "https://your-play-integrity-server.uc.r.appspot.com"

URL spesifik akan bervariasi, bergantung pada nama project dan region Google Cloud yang Anda gunakan untuk men-deploy server.

Membangun dan menjalankan

Menghubungkan perangkat Android yang dikonfigurasi untuk pengembangan. Di Android Studio, build project dan jalankan di perangkat yang terhubung. Aplikasi akan muncul seperti berikut:

Saat startup, aplikasi akan memanggil endpoint getRandom di server Anda dan menampilkan hasilnya. Jika terjadi error, seperti URL yang salah atau server tidak berfungsi, dialog error akan ditampilkan. Anda dapat memilih tombol Request Random untuk mengambil angka acak baru dari server. Tombol Call server with integrity check belum melakukan apa pun. Anda akan menambahkan fungsi tersebut di bagian berikut.

17. Menambahkan Play Integrity ke project (Kotlin)

Untuk menambahkan library Play Integrity dan dependensi pendukung ke project, lakukan langkah-langkah berikut:

Dari panel Project di Android Studio, buka file build.gradle di bagian start/app.
Temukan blok dependencies di bagian bawah file.
Tambahkan baris berikut ke bagian bawah blok dependencies:

    implementation "com.google.android.play:integrity:1.0.1"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-play-services:1.6.1"

Simpan file tersebut.
Di bagian atas file, banner akan muncul dan menginformasikan bahwa file Gradle telah berubah. Klik Sync Now untuk memuat ulang dan menyinkronkan ulang file.

Contoh Kotlin menggunakan coroutine. Library kotlinx-coroutines-play-services menambahkan ekstensi yang memfasilitasi penggunaan objek Task asinkron Play Integrity dari bagian dalam coroutine Kotlin.

18. Membuat permintaan integritas (Kotlin)

Dari panel Project di Android Studio, buka file IntegrityServer di bagian start/app/src/main/java/com.example.google.codelab.playintegritykotlin/integrity. Di bagian bawah file terdapat fungsi integrityCommand yang kosong. UI memanggil fungsi ini ketika tombol Call server with integrity check ditekan.

Anda akan menambahkan kode ke fungsi integrityCommand untuk melakukan operasi berikut:

Mengambil angka acak baru dari server untuk digunakan saat membuat nonce untuk dikaitkan dengan pemeriksaan integritas
Memanggil Play Integrity API untuk membuat permintaan integritas, dan menerima token integritas yang berisi hasilnya
Mengirim token perintah dan integritas ke server Anda menggunakan permintaan POST HTTP
Memproses dan menampilkan hasil

Tambahkan kode berikut ke fungsi integrityCommand yang kosong:

        // Set our state to working to trigger a switch to the waiting UI
        _serverState.emit(ServerState(
            ServerStatus.SERVER_STATUS_WORKING))
        // Request a fresh random from the server as part
        // of the nonce we will generate for the request
        var integrityRandom = IntegrityRandom("", 0U)
        try {
            val returnedRandom = httpClient.get<IntegrityRandom>(
                SERVER_URL + "/getRandom")
            integrityRandom = returnedRandom
        } catch (t: Throwable) {
            Log.d(TAG, "getRandom exception " + t.message)
            _serverState.emit(ServerState(ServerStatus.SERVER_STATUS_UNREACHABLE,
                IntegrityRandom("", 0U)))
        }

        // If we have a random, we are ready to request an integrity token
        if (!integrityRandom.random.isNullOrEmpty()) {
            val nonceString = GenerateNonce.GenerateNonceString(TEST_COMMAND,
                integrityRandom.random)
            // Create an instance of an IntegrityManager
            val integrityManager = IntegrityManagerFactory.create(context)

            // Use the nonce to configure a request for an integrity token
            try {
                val integrityTokenResponse: Task<IntegrityTokenResponse> =
                    integrityManager.requestIntegrityToken(
                        IntegrityTokenRequest.builder()
                            .setNonce(nonceString)
                            .build()
                    )
                // Wait for the integrity token to be generated
                integrityTokenResponse.await()
                if (integrityTokenResponse.isSuccessful && integrityTokenResponse.result != null) {
                    // Post the received token to our server
                    postCommand(integrityTokenResponse.result!!.token(), integrityRandom)
                } else {
                    Log.d(TAG, "requestIntegrityToken failed: " +
                            integrityTokenResponse.result.toString())
                    _serverState.emit(ServerState(ServerStatus.SERVER_STATUS_FAILED_TO_GET_TOKEN))
                }
            } catch (t: Throwable) {
                Log.d(TAG, "requestIntegrityToken exception " + t.message)
                _serverState.emit(ServerState(ServerStatus.SERVER_STATUS_FAILED_TO_GET_TOKEN))
            }
        }

Kode untuk melakukan POST perintah ke server Anda telah dipecah menjadi fungsi postCommand yang terpisah. Tambahkan kode berikut ke fungsi postCommand yang kosong:

        try {
            val commandResult = httpClient.post<CommandResult>(
                SERVER_URL + "/performCommand") {
                contentType(ContentType.Application.Json)
                body = ServerCommand(TEST_COMMAND, tokenString)
            }
            _serverState.emit(ServerState(ServerStatus.SERVER_STATUS_REACHABLE,
                integrityRandom,
                commandResult.diagnosticMessage,
                commandResult.commandSuccess,
                commandResult.expressToken))
        } catch (t: Throwable) {
            Log.d(TAG, "performCommand exception " + t.message)
            _serverState.emit(ServerState(ServerStatus.SERVER_STATUS_UNREACHABLE))
        }

Selesaikan impor yang hilang, lalu simpan file.

19. Menampilkan hasil (Kotlin)

Mengupdate UI dengan ringkasan verdict

UI saat ini menampilkan teks placeholder untuk ringkasan verdict integritas. Untuk mengganti placeholder dengan ringkasan yang sebenarnya, lakukan langkah-langkah berikut:

Dari panel Project di Android Studio, buka file MainView.kt di bagian start/app/src/main/java/com.example.google.codelab.playintegritykotlin/ui/main.
Lihat bagian akhir fungsi MainUI, temukan pernyataan text = "None",, dan ganti dengan kode ini:

                        text = state.serverState.serverVerdict,

Selesaikan impor yang hilang, lalu simpan file.

20. Membangun dan mengupload (Kotlin)

Membuat dan menyiapkan keystore untuk aplikasi

Android mewajibkan semua aplikasi ditandatangani secara digital dengan sertifikat sebelum diinstal atau diupdate di perangkat.

Membuat keystore dan membangun App Bundle rilis

Mengupload ke Konsol Play

Setelah membuat file App Bundle, upload ke Konsol Play. Sebaiknya gunakan jalur pengujian internal untuk memfasilitasi akses ke build Anda dengan cepat.

Menjalankan build pengujian

Sekarang Anda harus mendownload dan menjalankan build pengujian dari Play Store. Pemilihan tombol Call server with integrity check akan berhasil dan menghasilkan tampilan berikut:

21. Selamat

Selamat, Anda berhasil menambahkan Play Integrity ke aplikasi Android.

Bacaan lebih lanjut

Play Integrity