Mendaftarkan nama paket dengan Android Developer Console API

Android Developer Console API adalah antarmuka publik yang dirancang untuk memungkinkan distributor aplikasi dan developer perorangan mendaftarkan nama paket secara terprogram di Konsol Developer Android.

Kemampuan server ke server Anda sebagai:

Distributor aplikasi Developer perorangan
Daftarkan kunci nama paket atas nama developer yang memublikasikan aplikasi ke app store. Mendaftarkan nama paket dengan kunci yang dikelola Play Store. Membuktikan kepemilikan kunci yang terkait dengan nama paket. Daftarkan nama paket - kunci dalam alur kerja continuous deployment Anda. Membuktikan kepemilikan kunci yang terkait dengan nama paket.

Sebelum memulai

Sebelum memulai, Anda harus memiliki:

  1. Akses administratif ke project Google Cloud.
  2. Pemahaman dasar tentang:

Anda juga harus memahami istilah berikut:

Istilah Definisi
Akun developer Merepresentasikan akun Konsol Developer Android yang dapat memiliki satu atau beberapa nama paket. Objek ini berisi status verifikasi (NOT_VERIFIED atau VERIFIED).
Nama paket Nama paket Android tertentu (misalnya, com.example.app) dalam akun developer, yang dapat dikaitkan dengan satu atau beberapa kunci. Objek ini berisi status pendaftaran (DRAFT, IN_REVIEW, REGISTERED, atau PENDING_TRANSFER).
Kunci Sertifikat/kunci publik tertentu yang digunakan untuk menandatangani nama paket Android. Mencakup hash SHA-256 dan status pendaftaran saat ini (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED, atau PENDING_TRANSFER).

Mulai

Selesaikan langkah-langkah berikut untuk mengakses Android Developer Console API:

Membuat project Google Cloud

  1. Buat akun Google Cloud jika Anda belum memilikinya.
  2. Buka Konsol Google Cloud.
  3. Buat project Google Cloud.

Mengaktifkan API di project Google Cloud Anda

  1. Buka Konsol Google Cloud.
  2. Di menu navigasi (☰), pilih APIs & Services > Library.
  3. Pilih project Google Cloud tempat Anda ingin mengaktifkan API dari menu drop-down project.
  4. Gunakan kotak penelusuran APIs & Services untuk memilih Konsol Developer Android API.
  5. Aktifkan API:
    1. Buka halaman ringkasan API dengan memilihnya dari hasil penelusuran.
    2. Klik tombol Enable berwarna biru. Google Cloud mengaktifkan API untuk project yang Anda pilih, yang biasanya hanya memerlukan waktu beberapa saat. Setelah diaktifkan, Anda dapat mulai menggunakannya.

Mengautentikasi API

Untuk melakukan panggilan ke Android Developer Console API, Anda harus mengautentikasi permintaan menggunakan OAuth 2.0.

Melakukan autentikasi dengan OAuth 2.0

Android Developer Console API memerlukan autentikasi OAuth 2.0 untuk mengizinkan akses ke resource akun developer dan nama paket. Karena data akun developer terikat ke Akun Google pengguna, bukan project Google Cloud, Akun Layanan, Workload Identity Federation, dan kunci API tidak dapat digunakan untuk mengautentikasi permintaan API.

Cakupan OAuth 2.0

Cakupan berikut diperlukan untuk semua operasi:

Cakupan OAuth 2.0 Deskripsi
https://www.googleapis.com/auth/androiddeveloperconsole Melihat dan mengelola nama paket dan data di akun Konsol Developer Android Anda

Menerapkan alur Server Web OAuth 2.0

Untuk berintegrasi dengan Konsol Developer Android API, aplikasi harus menggunakan alur Server Web OAuth 2.0. Bergantung pada jenis aplikasi dan kebutuhan otomatisasi, Anda dapat memilih antara dua strategi pengelolaan kredensial utama:

Opsi A (Direkomendasikan): Akses offline / otomatis (integrasi CI/CD & server) Opsi B: Akses efemeral / interaktif
Strategi ini memungkinkan proses otomatis (seperti pipeline CI/CD) berjalan di latar belakang tanpa intervensi manusia:

Penyiapan izin pengguna satu kali: Selama penyiapan awal, developer atau pemilik akun menyelesaikan alur izin satu kali di browser mereka. Aplikasi Anda meminta akses offline (access_type=offline) bersama dengan cakupan API. Google menampilkan kode otorisasi, yang ditukarkan oleh aplikasi Anda dengan token akses awal dan token refresh yang memiliki masa aktif lama.

Eksekusi latar belakang: Simpan refresh_token dengan aman di lingkungan deployment atau pengelola secret Anda (misalnya, GitHub Actions Secrets, Google Secret Manager). Untuk panggilan API berikutnya, alur kerja otomatis Anda menggunakan token refresh yang disimpan untuk mendapatkan token akses berumur pendek yang baru sesuai permintaan, tanpa perlu login manual atau perintah 2FA. 		Jika Anda memilih untuk tidak menyimpan token refresh yang berumur panjang di lingkungan Anda, atau jika aplikasi Anda berjalan dalam konteks pengguna interaktif:

Prompt saat eksekusi: Jangan meminta akses offline atau menyimpan token refresh. Setiap kali alat atau aplikasi dijalankan, minta pengguna untuk melakukan autentikasi dengan mengalihkannya ke halaman izin Google OAuth di browser mereka.

Akses berumur singkat: Pengguna login dan memberikan izin, dan aplikasi menerima token akses berumur singkat secara langsung (atau menggunakan pertukaran kode otorisasi). Token akses ini digunakan untuk melakukan panggilan API dan dihapus setelah eksekusi. Eksekusi di masa mendatang mengharuskan pengguna untuk melakukan autentikasi ulang.

Mendaftarkan nama paket

Pendaftaran nama paket adalah proses pengaitan kunci dengan nama paket. Cara kunci didaftarkan bergantung pada apakah Anda mendaftarkan kunci ke nama paket baru atau yang sudah ada di Android.

Mendaftarkan nama paket baru

Untuk nama paket baru yang belum pernah terlihat di Android, Anda dapat memberikan public key certificate dari pasangan kunci penandatanganan aplikasi.

Mendaftarkan nama paket yang sudah ada

Untuk mendaftarkan nama paket yang sudah ada, Anda harus membuktikan kepemilikan kunci penandatanganan pribadi yang diketahui. Tidak seperti pendaftaran baru, API akan menampilkan daftar sidik jari sertifikat publik yang diketahui dan memenuhi syarat untuk pendaftaran. Kunci ini dapat digunakan untuk pendaftaran langsung.

Jika kunci yang Anda daftarkan tercantum sebagai "memerlukan justifikasi", Anda tetap dapat mendaftarkannya, tetapi selain menyelesaikan bukti kepemilikan, developer juga harus mengirimkan justifikasi untuk menggunakan nama paket tersebut.

Aturan kelayakan utama

Daftar kunci yang memenuhi syarat ditentukan oleh aturan kelayakan nama paket yang dirancang untuk meminimalkan berbagi nama paket (diperkenalkan sebagai bagian dari verifikasi developer Android).

Dalam skenario ketika nama paket digunakan oleh beberapa developer atau memiliki beberapa kunci penandatanganan, kelayakan ditentukan sebagai berikut:

Skenario Aturan untuk pendaftaran langsung Aturan untuk developer lain
Pemegang kunci mayoritas Kunci yang menyumbang lebih dari 50% dari total penginstalan yang diketahui memiliki prioritas. Semua developer lainnya harus memberikan alasan.
50+ penginstalan Jika tidak ada satu kunci yang memiliki >50% penginstalan, semua kunci dengan 50 penginstalan atau lebih memenuhi syarat. Developer dengan kunci yang memiliki kurang dari 50 penginstalan harus memberikan justifikasi.
Kurang dari 50 penginstalan Jika tidak ada kunci yang memenuhi batas 50 penginstalan, kunci apa pun dapat digunakan berdasarkan prinsip siapa cepat dia dapat Setelah satu developer mendaftar, developer lain harus memberikan alasan.

Memverifikasi kepemilikan kunci

Untuk menyelesaikan verifikasi nama paket yang sudah ada, API menyediakan string verifikasi. String verifikasi ini harus disertakan di dalam file baru bernama adi-registration.properties di dalam folder aset aplikasi. Kemudian, Anda harus menandatangani dan mengupload APK menggunakan kunci pribadi yang sesuai dengan kunci publik yang Anda daftarkan.

Menjustifikasi pendaftaran kunci

Jika pendaftaran kunci memerlukan justifikasi, developer harus mengirimkan alasan bisnis yang mendetail. Google akan meninjau justifikasi ini, dan persetujuan untuk pendaftaran nama paket dapat memerlukan waktu hingga 24 jam.

Praktik terbaik pengalaman pengguna

Sebaiknya aplikasi yang menggunakan Android Developer Console API mengikuti pola ini untuk memastikan integrasi yang lancar.

Menetapkan konteks otorisasi OAuth yang jelas

Memberikan konteks eksplisit sebelum meminta otorisasi OAuth membantu developer memahami alasan akses akun diperlukan. Untuk memandu pengguna secara efektif, berikan penjelasan yang jelas tentang fungsi yang diharapkan sebelum meluncurkan layar izin OAuth.

Buat struktur konteks otorisasi menggunakan format berikut:

  • Judul: "Tautkan akun Konsol Developer Android Anda"
  • Ringkasan: "Kelola pendaftaran nama paket untuk verifikasi developer Android dalam [application-name]"
  • Tombol Tindakan: Tombol "Lanjutkan dengan Google" atau "Login dengan Google"
Dialog yang menggambarkan konteks otorisasi OAuth untuk menautkan akun.
Gambar 1. Tautkan akun Konsol Developer Android Anda.

Mengidentifikasi akun developer

  1. Lakukan integrasi dengan metode API ListDeveloperAccounts untuk mengambil dan mencantumkan semua akun developer yang aksesnya telah diizinkan.
  2. Menyediakan alat pilih akun untuk memungkinkan developer memilih akun developer pilihannya.
  3. Tampilkan akun displayName secara jelas, menggunakan nomor rekening dari kolom name sebagai informasi sekunder.
  4. Menampilkan status verifikasi akun (verificationState):
    • VERIFIED: Konfirmasi identitas developer terverifikasi dengan isyarat visual positif (misalnya, tanda centang hijau).
    • NOT_VERIFIED: Menunjukkan bahwa verifikasi belum selesai dan membatasi pendaftaran paket untuk akun. Secara opsional, sediakan tombol CTA utama yang mengarahkan developer ke Konsol Developer Android setelah memilih akun.
Pemilih akun yang menampilkan nama akun developer dan status verifikasi.
Gambar 2. Pemilih akun yang menampilkan akun developer dan status verifikasi.

Jika respons kosong diterima karena tidak ada akun developer yang terkait dengan Akun Google, arahkan developer ke Konsol Developer Android menggunakan tombol CTA utama.

Mengelola nama paket

  1. Lakukan integrasi dengan endpoint API ListAndroidPackages untuk mengambil semua nama paket yang terkait dengan akun developer. Menyediakan antarmuka terpusat, seperti daftar atau tabel, bagi developer untuk memantau status paket mereka secara efektif.
  2. Tampilkan packageName bersama status pendaftarannya saat ini (DRAFT, IN_REVIEW, REGISTERED, atau PENDING_TRANSFER), dengan menerapkan indikator visual yang berbeda untuk setiap status. Jika "nama yang mudah diingat" diberikan dan disimpan selama pembuatan, Anda dapat menyertakannya dalam tampilan.
Antarmuka yang menampilkan nama paket terdaftar dan statusnya.
Gambar 3. Antarmuka untuk mengelola nama paket dan status pendaftaran.

Mengelola kunci

  1. Panggil endpoint API ListAndroidPackageKeys untuk mengambil semua kunci yang terkait dengan nama paket, sehingga developer mendapatkan ringkasan terstruktur (seperti tabel atau daftar) untuk memantau status pendaftaran mereka.
  2. Tampilkan certificateFingerprintSha256 untuk setiap kunci beserta status pendaftarannya (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE, atau PENDING_TRANSFER), menggunakan indikator visual yang berbeda untuk membedakan status.
Daftar sidik jari sertifikat dan status pendaftaran kunci.
Gambar 4. Ringkasan kunci dan status pendaftarannya.
  1. Memungkinkan developer mendaftarkan kunci tambahan dengan nama paket yang ada dengan mengintegrasikan metode API CreateAndroidPackageKey.

Mendaftarkan nama paket

  1. Gunakan tata letak berbasis formulir tempat developer memasukkan nama paket mereka ke dalam kolom teks, asalkan informasi ini belum dikumpulkan oleh aplikasi Anda (misalnya, melalui perintah sebelumnya).
  2. Panggil metode API CreateAndroidPackage untuk mendaftarkan nama paket di akun developer, dan panggil metode API GetAndroidPackageRegistrationPolicy untuk menentukan aturan kelayakan kunci yang berlaku.
  3. Berdasarkan keySelectionStrategy yang ditetapkan untuk nama paket, minta developer untuk melakukan salah satu tindakan berikut:
    • Jika keySelectionStrategy ditetapkan ke SELECT_KEY_FROM_LIST: Minta developer memilih kunci untuk pendaftaran dari daftar knownKeys yang disediakan (berisi sidik jari sertifikat SHA-256), seperti menggunakan tombol pilihan. Alur ini memerlukan verifikasi kepemilikan kunci (lihat Memverifikasi kepemilikan kunci di bawah).
    • Jika keySelectionStrategy ditetapkan ke USE_ANY_KEY: Minta developer untuk memberikan kunci secara langsung. Verifikasi kepemilikan kunci tidak diperlukan dalam kasus ini.
  4. Panggil metode API CreateAndroidPackageKey untuk mengaitkan kunci yang dipilih dengan nama paket baru.
Formulir untuk mendaftarkan nama paket dan memilih kunci penandatanganan.
Gambar 5. Alur untuk mendaftarkan nama paket dan memilih kunci.

Atau, aplikasi Anda dapat otomatis mendeteksi dan mengekstrak nama paket atau kunci langsung dari aplikasi yang diupload.

Memverifikasi kepemilikan kunci

Jika keySelectionStrategy ditetapkan ke SELECT_KEY_FROM_LIST, developer harus membuktikan kepemilikan kunci penandatanganan pribadi mereka. Bukti kepemilikan memerlukan pengiriman APK yang ditandatangani dan menyertakan verificationToken yang dihasilkan API.

Untuk mendukung verifikasi kepemilikan kunci, integrasikan metode API VerifyAndroidPackageKeyOwnership dan bangun komponen antarmuka pengguna berikut:

  • Komponen tampilan token: Menampilkan verificationToken secara jelas di dalam blok cuplikan kode, termasuk tombol "Salin ke Papan Klip" yang praktis.
  • Petunjuk penyiapan developer: Berikan petunjuk mendetail yang mengarahkan developer untuk menempatkan file adi-registration.properties yang berisi verificationToken ke dalam folder aset aplikasi.
  • Dropzone pengiriman APK: Menawarkan dropzone upload file khusus untuk menerima APK yang ditandatangani.
Zona lepas dan tampilan token untuk memverifikasi kepemilikan kunci.
Gambar 6. Komponen UI untuk memverifikasi kepemilikan kunci dengan upload APK yang ditandatangani.

Menjustifikasi pendaftaran kunci

Jika kunci yang diketahui memiliki kolom justificationRequired yang ditetapkan ke REQUIRED, mendaftarkan kunci tersebut bersama dengan nama paket mengharuskan developer mengirimkan alasan bisnis yang menyeluruh.

Kirimkan justifikasi ini dengan memanggil metode API JustifyAndroidPackageKeyRegistration. Pastikan antarmuka pengguna aplikasi Anda memiliki area input teks khusus untuk mengumpulkan justifikasi dari developer, dan beri tahu mereka bahwa pemberian alasan diperlukan sebelum mengirimkan permintaan pendaftaran kunci. Google akan meninjau justifikasi yang dikirimkan, sebuah proses yang dapat memerlukan waktu hingga 24 jam untuk disetujui sebelum pendaftaran nama paket selesai.

Mengotomatiskan verifikasi kunci untuk kunci terkelola

Jika aplikasi Anda mengelola kunci penandatanganan developer, developer tidak dapat menandatangani APK secara manual untuk verifikasi kepemilikan. Sebagai gantinya, Anda harus menjalankan panggilan API VerifyAndroidPackageKeyOwnership secara otomatis atas nama mereka.

Dengan menangani proses penyertaan token dan upload APK secara otomatis, aplikasi Anda akan menghilangkan langkah-langkah manual ini. Pastikan untuk memberi tahu developer bahwa verifikasi kepemilikan kunci dikelola dengan lancar oleh aplikasi Anda menggunakan kunci yang disimpan di sistem Anda.

Mengikuti pedoman merek

Untuk menjaga kepercayaan pengguna dan memastikan transparansi, semua aplikasi yang berintegrasi dengan Android Developer Console API harus mematuhi pedoman merek berikut.

Terminologi dan kapitalisasi

Saat merujuk ke produk dalam materi atau dokumentasi yang ditampilkan kepada pengguna, selalu gunakan nama lengkap Konsol Developer Android. Jangan gunakan singkatan "ADC".

Program ini harus disebut sebagai verifikasi developer Android. Ikuti kapitalisasi dan ejaan yang sama persis ini dalam semua konteks.

Untuk mencegah ambiguitas dengan APK atau AAB, gunakan istilah "nama paket" secara khusus, bukan hanya "paket".

Saat menjelaskan proses penambahan nama paket, gunakan frasa "mendaftarkan nama paket", bukan "mengklaim nama paket".

Menggunakan pesan ajakan (CTA) "Login"

Autentikasi OAuth 2.0 dengan Konsol Developer Android mengandalkan Layanan Identitas Google. Agar tetap mematuhi panduan branding Google Identity Services, Anda harus menggunakan pesan ajakan (CTA) "Lanjutkan dengan Google" atau "Login dengan Google" pada tombol otorisasi. Teks ini wajib ada dan tidak dapat diubah, karena teks ini memastikan pengguna memahami bahwa mereka menggunakan kredensial Google mereka untuk mengizinkan aplikasi Anda mengakses Akun Google mereka.

Menjaga identitas dan integritas merek

Saat mengintegrasikan logo Konsol Developer Android ke antarmuka aplikasi, Anda harus mengikuti spesifikasi berikut untuk mempertahankan identitas visual dan integritas merek:

  • Penempatan dan hierarki logo: Hanya gunakan logo Konsol Developer Android resmi yang disetujui. Logo harus selalu menjadi elemen sekunder dari elemen branding utama aplikasi Anda sendiri untuk menghindari kesalahan representasi aplikasi sebagai produk resmi Google.
Logo resmi Konsol Developer Android. Klik untuk menyimpan file.
Gambar 7. Logo resmi Konsol Developer Android. Klik gambar untuk menyimpan file.
  • Gaya visual dan distorsi: Aset harus selalu dirender dengan rasio aspek yang sepenuhnya dibatasi. Anda tidak boleh mendistorsi, meregangkan, memiringkan, memangkas, membalik, atau mengubah komponen logo. Jangan mengubah palet warna resmi, menukar warna latar depan atau latar belakang, atau menerapkan drop shadow, efek cahaya, atau gradien dekoratif.
  • Batasan penggunaan: Jangan memasukkan elemen branding milik Google ke dalam aset aplikasi Anda sendiri. Aset logo Konsol Developer Android hanya dapat digunakan di dalam konteks tata letak aplikasi untuk menandakan integrasi aktif secara eksplisit.

Referensi lainnya