Referensi Pemberian Lisensi

Class dan Antarmuka LVL

Tabel 1 mencantumkan semua file asal di Library Verifikasi Lisensi (LVL) yang tersedia melalui Android SDK. Semua file tersebut adalah bagian dari paket com.android.vending.licensing.

Tabel 1. Ringkasan class dan antarmuka library LVL.

Kategori Nama Deskripsi
Pemeriksaan dan hasil lisensi LicenseChecker Class (atau subclass) yang Anda buat instance-nya untuk memulai pemeriksaan lisensi.
LicenseCheckerCallback Antarmuka yang Anda terapkan untuk menangani hasil pemeriksaan lisensi.
Kebijakan Kebijakan Antarmuka yang Anda implementasikan untuk menentukan apakah akan mengizinkan akses ke aplikasi tersebut, berdasarkan pada respons lisensi.
ServerManagedPolicy Implementasi Policy default Menggunakan setelan yang disediakan oleh server pemberian lisensi untuk mengelola penyimpanan lokal data lisensi, validitas lisensi, percobaan ulang.
StrictPolicy Implementasi Policy alternatif. Menerapkan pemberian lisensi berdasarkan pada respons lisensi langsung hanya dari server. Tanpa men-cache atau mencoba ulang permintaan.
Obfuscation data
(opsional)
Obfuscator Antarmuka yang Anda implementasikan jika menggunakan Policy (seperti ServerManagedPolicy) yang men-cache data respons lisensi di penyimpanan persisten. Menerapkan algoritme obfuscation untuk mengenkode dan mendekode data yang sedang ditulis atau dibaca.
AESObfuscator Implementasi Obfuscator default yang menggunakan algoritme enkripsi/dekripsi AES untuk meng-obfuscate/membatalkan obfuscation data.
Pembatasan perangkat
(opsional)
DeviceLimiter Antarmuka yang Anda implementasikan jika ingin membatasi penggunaan aplikasi pada perangkat tertentu. Dipanggil dari LicenseValidator. Implementasi DeviceLimiter tidak direkomendasikan untuk sebagian besar aplikasi karena memerlukan server backend dan mungkin akan menyebabkan pengguna kehilangan akses ke aplikasi berlisensi, kecuali apabila didesain dengan hati-hati.
NullDeviceLimiter Implementasi DeviceLimiter default yang dilakukan tanpa pengoperasian (memungkinkan akses ke semua perangkat).
Inti library, tidak memerlukan integrasi ResponseData Class yang memiliki kolom respons lisensi.
LicenseValidator Class yang mendekripsi dan memverifikasi respons yang diterima dari server pemberian lisensi.
ValidationException Class yang mengindikasikan error yang terjadi saat memvalidasi integritas data yang dikelola oleh Obfuscator.
PreferenceObfuscator Class utilitas yang menulis/membaca data yang di-obfuscate ke penyimpanan SharedPreferences sistem.
ILicensingService Antarmuka IPC sekali jalan tempat permintaan pemeriksaan lisensi diteruskan ke klien Google Play.
ILicenseResultListener Implementasi callback IPC sekali jalan tempat aplikasi menerima respons asinkron dari server pemberian lisensi.

Kode Respons Server

Tabel 2 mencantumkan semua kode respons lisensi yang didukung oleh server pemberi lisensi. Secara umum, aplikasi sebaiknya menangani semua kode respons ini. Secara default, class LicenseValidator di LVL menyediakan semua penanganan kode respons yang diperlukan untuk Anda.

Tabel 2. Ringkasan kode respons yang ditampilkan oleh server Google Play dalam respons lisensi.

Kode Respons Deskripsi Ditandatangani? Tambahan Komentar
LICENSED Aplikasi ini dilisensikan kepada pengguna. Pengguna telah membeli aplikasi, atau diizinkan untuk mendownload dan menginstal aplikasi versi alfa atau beta. Ya VTGT, GR Mengizinkan akses menurut batasan Policy.
LICENSED_OLD_KEY Aplikasi dilisensikan kepada pengguna, tetapi tersedia versi aplikasi terupdate yang ditandatangani dengan kunci yang berbeda. Ya VT, GT, GR, UT Mengizinkan akses secara opsional menurut batasan Policy.

Dapat mengindikasikan bahwa pasangan kunci yang digunakan oleh versi aplikasi yang diinstal tidak valid atau disusupi. Aplikasi dapat mengizinkan akses jika diperlukan atau memberi tahu pengguna bahwa upgrade telah tersedia dan membatasi penggunaan lebih lanjut hingga upgrade dilakukan.

NOT_LICENSED Aplikasi ini tidak dilisensikan kepada pengguna. Tidak Tidak mengizinkan akses.
ERROR_CONTACTING_SERVER Error lokal — aplikasi Google Play tidak dapat menjangkau server pemberian lisensi, yang mungkin disebabkan oleh masalah ketersediaan jaringan. Tidak Mencoba ulang pemeriksaan lisensi menurut batas percobaan ulang Policy.
ERROR_SERVER_FAILURE Error server — server tidak dapat memuat pasangan kunci aplikasi untuk pemberian lisensi. Tidak Mencoba ulang pemeriksaan lisensi menurut batas percobaan ulang Policy.
ERROR_INVALID_PACKAGE_NAME Error lokal — aplikasi meminta pemeriksaan lisensi untuk paket yang tidak diinstal pada perangkat. Tidak Tidak mencoba ulang pemeriksaan lisensi.

Biasanya disebabkan oleh error pengembangan.

ERROR_NON_MATCHING_UID Error lokal — aplikasi meminta pemeriksaan lisensi untuk paket yang UID-nya (paket, pasangan ID pengguna) tidak cocok dengan aplikasi yang mengajukan permintaan. Tidak Tidak mencoba ulang pemeriksaan lisensi.

Biasanya disebabkan oleh error pengembangan.

ERROR_NOT_MARKET_MANAGED Error server — aplikasi (nama paket) tidak dikenali oleh Google Play. Tidak Tidak mencoba ulang pemeriksaan lisensi.

Dapat mengindikasikan bahwa aplikasi tidak dipublikasikan melalui Google Play atau terdapat error pengembangan dalam implementasi pemberian lisensi.

Catatan: Sebagaimana didokumentasikan dalam Menyiapkan Lingkungan Pengujian, kode respons dapat diganti secara manual untuk developer aplikasi dan semua pengguna pengujian yang terdaftar melalui Konsol Google Play.

Catatan: Sebelumnya Anda dapat menguji aplikasi dengan mengupload versi "draf" yang tidak dipublikasikan. Fungsi ini tidak lagi didukung; sebagai gantinya, Anda harus memublikasikannya ke saluran distribusi alfa atau beta. Untuk informasi selengkapnya, lihat Aplikasi Draf Tidak Lagi Didukung.

Tambahan Respons Server

Untuk membantu aplikasi Anda dalam mengelola akses ke aplikasi pada periode pengembalian dana aplikasi dan menyediakan informasi lainnya, server pemberian lisensi menyertakan beberapa bagian informasi dalam respons lisensi. Secara khusus, layanan tersebut menyediakan nilai yang direkomendasikan untuk periode validitas lisensi aplikasi, masa tenggang percobaan ulang, jumlah percobaan ulang maksimum yang diizinkan dan setelan lainnya. Jika aplikasi Anda menggunakan file perluasan APK, respons juga menyertakan nama file, ukuran, dan URL. Server menambahkan setelan sebagai key-value pair di kolom "tambahan" respons lisensi.

Setiap implementasi Policy dapat mengekstrak setelan tambahan dari respons lisensi dan menggunakannya sesuai kebutuhan. Implementasi Policy default LVL, ServerManagedPolicy, berperan sebagai implementasi yang berfungsi dan ilustrasi tentang cara memperoleh, menyimpan, dan menggunakan setelan.

Tabel 3. Ringkasan setelan pengelolaan lisensi yang disediakan oleh server Google Play dalam respons lisensi.

TambahanDeskripsi
VT Stempel waktu validitas lisensi. Menentukan tanggal/waktu saat respons lisensi (yang di-cache) saat ini habis masa berlakunya dan harus diperiksa ulang di server pemberian lisensi. Lihat bagian di bawah tentang Periode validitas lisensi.
GT Stempel waktu masa tenggang. Menentukan masa berakhir periode selama Kebijakan memungkinkan akses ke aplikasi walaupun status responsnya adalah RETRY.

Nilai dikelola oleh server, tetapi nilai standar adalah 5 hari atau lebih. Lihat bagian di bawah tentang Periode percobaan ulang dan jumlah percobaan ulang maksimum.

GR Jumlah percobaan ulang maksimum. Menentukan jumlah pemeriksaan lisensi RETRY secara berturut-turut yang Policy harus izinkan, sebelum menolak akses pengguna ke aplikasi.

Nilai dikelola oleh server, tetapi nilai standar adalah "10" atau lebih tinggi. Lihat bagian di bawah ini tentang Periode percobaan ulang dan jumlah percobaan ulang maksimum.

UT Stempel waktu update. Menentukan hari/waktu saat update terbaru aplikasi ini diupload dan dipublikasikan.

Server akan menampilkan nilai tambahan ini hanya untuk respons LICENSED_OLD_KEYS, guna memungkinkan Policy menentukan lamanya waktu yang berlalu sejak update dipublikasikan dengan kunci lisensi baru sebelum menolak akses pengguna ke aplikasi.

FILE_URL1 atau FILE_URL2 URL untuk file perluasan (1 untuk file utama, 2 adalah file patch). Gunakan ini untuk mendownload file melalui HTTP.
FILE_NAME1 atau FILE_NAME2 Nama file perluasan (1 untuk file utama, 2 adalah file patch). Anda harus menggunakan nama ini saat menyimpan file pada perangkat.
FILE_SIZE1 atau FILE_SIZE2 Ukuran file dalam byte (1 untuk file utama, 2 adalah file patch). Gunakan ini untuk membantu proses download dan memastikan ketersediaan ruang yang cukup di lokasi penyimpanan bersama pada perangkat sebelum mendownload.

Periode validitas lisensi

Server pemberian lisensi Google Play menetapkan periode validitas lisensi untuk semua aplikasi yang didownload. Periode tersebut menyatakan interval waktu pada status lisensi aplikasi harus dianggap tidak berubah dan dapat di-cache oleh Policy pemberian lisensi di aplikasi. Server pemberian lisensi menyertakan periode validitas dalam responsnya untuk semua pemeriksaan lisensi, yang menambahkan stempel waktu akhir validitas ke respons sebagai tambahan pada VT kunci. Policy dapat mengekstrak nilai kunci VT dan menggunakannya untuk mengizinkan akses ke aplikasi secara bersyarat tanpa memeriksa ulang lisensi, hingga periode validitas berakhir.

Validitas lisensi memberi tanda pada Policy pemberian lisensi saat validitas lisensi harus memeriksa ulang status pemberian lisensi dengan server pemberian lisensi. Validitas lisensi tidak dimaksudkan untuk mengisyaratkan apakah aplikasi benar-benar dilisensikan untuk digunakan. Yaitu, saat periode validitas lisensi aplikasi berakhir, hal ini bukan berarti aplikasi tidak lagi dilisensikan untuk digunakan, tetapi, hanya mengindikasikan bahwa Policy harus memeriksa ulang status pemberian lisensi dengan server. Dengan demikian, selama periode validitas lisensi belum berakhir, Policy boleh men-cache status lisensi awal secara lokal dan menampilkan status lisensi yang di-cache bukan mengirim pemeriksaan lisensi yang baru ke server.

Server pemberian lisensi mengelola periode validitas sebagai sarana untuk membantu aplikasi menerapkan pemberian lisensi dengan benar di seluruh periode pengembalian dana yang ditawarkan oleh Google Play untuk aplikasi berbayar. Server lisensi menetapkan periode validitas berdasarkan pada apakah aplikasi telah dibeli dan, jika telah dibeli, sudah berapa lama berlangsung. Secara khusus, server menetapkan periode validitas sebagai berikut:

  • Untuk aplikasi berbayar, server menetapkan periode validitas lisensi awal sehingga respons lisensi tetap valid selama dana aplikasi dapat dikembalikan. Policy pemberian lisensi pada aplikasi dapat men-cache hasil pemeriksaan lisensi awal dan tidak perlu memeriksa ulang lisensi hingga periode validitasnya telah berakhir.
  • Apabila dana aplikasi tidak dapat lagi dikembalikan, server akan menetapkan periode validitas yang lebih lama, biasanya selama beberapa hari.
  • Untuk aplikasi gratis, server menetapkan periode validitas ke nilai yang sangat tinggi (long.MAX_VALUE). Hal ini memastikan bahwa, selama Policy telah men-cache stempel waktu validitas secara lokal, pemeriksaan ulang status lisensi aplikasi tidak perlu dilakukan di masa mendatang.

Implementasi ServerManagedPolicy menggunakan stempel waktu yang diekstrak (mValidityTimestamp) sebagai syarat utama untuk menentukan apakah akan memeriksa ulang status lisensi dengan server sebelum mengizinkan akses pengguna ke aplikasi.

Periode percobaan ulang dan jumlah percobaan ulang maksimum

Dalam beberapa kasus, kondisi jaringan atau sistem dapat mencegah pemeriksaan lisensi aplikasi menjangkau server pemberian lisensi, atau mencegah respons server menjangkau aplikasi klien Google Play. Misalnya, pengguna mungkin meluncurkan aplikasi saat tidak ada jaringan seluler atau koneksi data tidak tersedia, seperti saat berada dalam pesawat, atau saat koneksi jaringan tidak stabil atau sinyal seluler lemah.

Saat masalah jaringan mencegah atau mengganggu pemeriksaan lisensi, klien Google Play akan memberi tahu aplikasi dengan menampilkan kode respons RETRY ke metode processServerResponse() Policy. Perihal masalah sistem, seperti saat aplikasi tidak dapat terikat dengan implementasi ILicensingService Google Play, library LicenseChecker itu sendiri akan memanggil metode processServerResonse() Policy dengan kode respons RETRY.

Secara umum, kode respons RETRY merupakan sinyal untuk memberi tahu aplikasi bahwa error yang menyebabkan pemeriksaan lisensi tidak dapat diselesaikan telah muncul.

Server Google Play membantu aplikasi untuk mengelola pemberian lisensi dalam kondisi error dengan menetapkan "masa tenggang" percobaan ulang dan jumlah percobaan ulang maksimum yang direkomendasikan. Server menyertakan nilai ini di semua respons pemeriksaan lisensi, menambahkannya sebagai tambahan pada kunci GT dan GR.

Policy aplikasi dapat mengekstrak tambahan GT dan GR dan menggunakannya untuk mengizinkan akses ke aplikasi secara bersyarat, sebagai berikut:

  • Untuk pemeriksaan lisensi yang menghasilkan respons RETRY, Policy harus men-cache kode respons RETRY dan menambahkan jumlah respons RETRY.
  • Policy harus mengizinkan pengguna untuk mengakses aplikasi, selama masa tenggang percobaan ulang masih aktif atau jumlah percobaan ulang maksimum belum tercapai.

ServerManagedPolicy menggunakan nilai GT dan GR yang disediakan oleh server seperti yang dijelaskan di atas. Contoh di bawah ini menunjukkan penanganan bersyarat dari respons percobaan ulang dalam metode allow(). Jumlah respons RETRY tidak ditampilkan, tetapi disimpan dalam metode processServerResponse().

Kotlin

fun allowAccess(): Boolean {
    val ts = System.currentTimeMillis()
    return when(lastResponse) {
        LICENSED -> {
            // Check if the LICENSED response occurred within the validity timeout.
            ts <= validityTimestamp  // Cached LICENSED response is still valid.
        }
        RETRY -> {
            ts < lastResponseTime + MILLIS_PER_MINUTE &&
                    // Only allow access if we are within the retry period
                    // or we haven't used up our max retries.
                    (ts <= retryUntil || retryCount <= maxRetries)
        }
        else -> false
    }
}

Java

public boolean allowAccess() {
    long ts = System.currentTimeMillis();
    if (lastResponse == LicenseResponse.LICENSED) {
        // Check if the LICENSED response occurred within the validity timeout.
        if (ts <= validityTimestamp) {
            // Cached LICENSED response is still valid.
            return true;
        }
    } else if (lastResponse == LicenseResponse.RETRY &&
                ts < lastResponseTime + MILLIS_PER_MINUTE) {
        // Only allow access if we are within the retry period
        // or we haven't used up our max retries.
        return (ts <= retryUntil || retryCount <= maxRetries);
    }
    return false;
}