Android Developer Console API ile paket adlarını kaydetme

Android Developer Console API, uygulama dağıtıcılarının ve bireysel geliştiricilerin Android Developer Console'da paket adlarını programatik olarak kaydetmesine olanak tanımak için tasarlanmış herkese açık bir arayüzdür.

Sunucudan sunucuya özellikleriniz:

App Distribution Bireysel geliştirici
Mağazada uygulama yayınlayan geliştirici adına bir paket adı-anahtar kaydedin. Mağaza tarafından yönetilen anahtarla paket adı kaydetme Bir paket adıyla ilişkili anahtarın sahibi olduğunuzu kanıtlayın. Sürekli dağıtım iş akışlarınızda bir paket adı-anahtar kaydedin. Paket adıyla ilişkili bir anahtarın sahibi olduğunuzu kanıtlayın.

Başlamadan önce

Başlamadan önce şunlara sahip olmanız gerekir:

  1. Bir Google Cloud projesine yönetim erişimi.
  2. Aşağıdakiler hakkında temel düzeyde bilgi:

Ayrıca aşağıdaki terimleri de bilmeniz gerekir:

Terim Tanım
Geliştirici hesabı Bir veya daha fazla paket adına sahip olabilen bir Android Developer Console hesabını temsil eder. Doğrulama durumu (NOT_VERIFIED veya VERIFIED) içerir.
Paket adı Bir geliştirici hesabındaki belirli bir Android paket adı (ör. com.example.app). Bu ad, bir veya daha fazla anahtarla ilişkilendirilebilir. Kayıt durumunu (DRAFT, IN_REVIEW, REGISTERED veya PENDING_TRANSFER) içerir.
Anahtar Android paket adını imzalamak için kullanılan belirli ortak sertifika/anahtar. SHA-256 karmasını ve mevcut kayıt durumunu (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED veya PENDING_TRANSFER) içerir.

Başlayın

Android Developer Console API'ye erişmek için aşağıdaki adımları tamamlayın:

Google Cloud projesi oluşturma

  1. Henüz bir hesabınız yoksa Google Cloud hesabı oluşturun.
  2. Google Cloud Console'u açın.
  3. Google Cloud projesi oluşturun.

Google Cloud projenizde API'yi etkinleştirme

  1. Google Cloud Console'u açın.
  2. Gezinme menüsünde (☰) API'ler ve Hizmetler > Kitaplık'ı seçin.
  3. Proje açılır menüsünden API'yi etkinleştirmek istediğiniz Google Cloud projesini seçin.
  4. Android Developer Console API'yi seçmek için API'ler ve Hizmetler arama çubuğunu kullanın.
  5. API'yi etkinleştirin:
    1. Arama sonuçlarından seçerek API'nin genel bakış sayfasına gidin.
    2. Mavi renkli Etkinleştir düğmesini tıklayın. Google Cloud, seçtiğiniz proje için API'yi etkinleştirir. Bu işlem genellikle kısa sürer. Etkinleştirildikten sonra kullanmaya başlayabilirsiniz.

API'nin kimliğini doğrulama

Android Developer Console API'ye çağrı yapmak için isteklerinizin kimliğini OAuth 2.0 kullanarak doğrulamanız gerekir.

OAuth 2.0 ile kimlik doğrulama

Android Developer Console API, geliştirici hesabı kaynaklarına ve paket adlarına erişimi yetkilendirmek için OAuth 2.0 kimlik doğrulaması gerektirir. Geliştirici hesabı verileri bir Google Cloud projesine değil, kullanıcının Google Hesabı'na bağlı olduğundan API isteklerinin kimliğini doğrulamak için hizmet hesapları, Workload Identity Federasyonu ve API anahtarları kullanılamaz.

OAuth 2.0 kapsamı

Tüm işlemler için aşağıdaki kapsam gereklidir:

OAuth 2.0 Kapsamı Açıklama
https://www.googleapis.com/auth/androiddeveloperconsole Android Developer Console hesaplarınızdaki paket adları ile verilerini görüntüleme ve yönetme

OAuth 2.0 web sunucusu akışını uygulama

Uygulamaların Android Developer Console API ile entegre olması için OAuth 2.0 web sunucusu akışını kullanması gerekir. Uygulama türünüze ve otomasyon ihtiyaçlarınıza bağlı olarak iki ana kimlik bilgisi yönetimi stratejisi arasından seçim yapabilirsiniz:

A Seçeneği (Önerilen): Çevrimdışı / otomatik erişim (CI/CD ve sunucu entegrasyonu) B seçeneği: Geçici / etkileşimli erişim
Bu strateji, otomatik süreçlerin (ör. CI/CD ardışık düzenleri) insan müdahalesi olmadan arka planda çalışmasına olanak tanır:

Tek seferlik kullanıcı izni kurulumu: İlk kurulum sırasında geliştirici veya hesap sahibi, tarayıcısında tek seferlik izin akışını tamamlar. Uygulamanız, API kapsamıyla birlikte çevrimdışı erişim (access_type=offline) istiyor. Google, uygulamanızın ilk erişim jetonu ve uzun ömürlü yenileme jetonu ile değiştirdiği bir yetkilendirme kodu döndürür.

Arka planda yürütme: refresh_token değerini dağıtım ortamınızda veya gizli anahtar yöneticinizde (ör. GitHub Actions Secrets, Google Secret Manager) güvenli bir şekilde saklayın. Sonraki API çağrılarında otomatik iş akışınız, depolanan yenileme jetonunu kullanarak kısa süreli yeni bir erişim jetonu alır ve manuel giriş veya iki faktörlü kimlik doğrulama istemlerini atlar. 		Ortamınızda uzun ömürlü yenileme jetonları depolamaktan kaçınmayı tercih ediyorsanız veya uygulamanız etkileşimli bir kullanıcı bağlamında çalışıyorsa:

Yürütme sırasında istemde bulunma: Çevrimdışı erişim istemeyin veya yenileme jetonu depolamayın. Araç veya uygulama her çalıştırıldığında, kullanıcıyı tarayıcısındaki Google OAuth izin sayfasına yönlendirerek kimlik doğrulaması yapmasını isteyin.

Kısa süreli erişim: Kullanıcı giriş yapıp izin verir ve uygulama doğrudan (veya yetkilendirme kodu değişimi kullanarak) kısa süreli bir erişim jetonu alır. Bu erişim jetonu, API çağrıları yapmak için kullanılır ve yürütme işleminden sonra silinir. Gelecekteki çalıştırmalar için kullanıcının yeniden kimlik doğrulaması yapması gerekir.

Paket adı kaydetme

Paket adı kaydı, bir anahtarı paket adıyla ilişkilendirme işlemidir. Anahtarın nasıl kaydedileceği, anahtarı Android'de yeni bir paket adına mı yoksa mevcut bir paket adına mı kaydettiğinize bağlıdır.

Yeni bir paket adı kaydetme

Android'de daha önce hiç görülmemiş yeni bir paket adı için uygulamanın imzalama anahtar çiftinden ortak anahtar sertifikasını sağlayabilirsiniz.

Mevcut bir paket adını kaydetme

Mevcut bir paket adını kaydetmek için bilinen bir özel imzalama anahtarının sahibi olduğunuzu kanıtlamanız gerekir. Yeni kayıttan farklı olarak API, kayda uygun olduğu bilinen herkese açık sertifika parmak izlerinin listesini döndürür. Bu anahtarlar doğrudan kayıt için kullanılabilir.

Kaydettiğiniz anahtar "gerekçe gerektiriyor" olarak listeleniyorsa anahtarı yine de kaydedebilirsiniz. Ancak geliştiricinin, sahipliği kanıtlayan bir belge sunmanın yanı sıra paket adını kullanma gerekçesini de göndermesi gerekir.

Temel uygunluk kuralları

Uygun anahtarların listesi, paket adı paylaşımını en aza indirmek için tasarlanmış paket adı uygunluk kurallarına göre belirlenir (Android geliştirici doğrulaması kapsamında geçerli olmuştur).

Bir paket adının, birden fazla geliştirici tarafından kullanıldığı veya birden fazla imzalama anahtarına sahip olduğu senaryolarda uygunluk aşağıdaki gibi belirlenir:

Senaryo Doğrudan kayıt kuralı Diğer geliştiricilerle ilgili kural
Çoğunluğun anahtar sahibi Bilinen toplam yüklemelerin %50'sinden fazlasından sorumlu anahtar önceliklidir. Diğer tüm geliştiricilerin gerekçe sunması gerekir.
50'den fazla yükleme Hiçbir anahtar, yüklemelerin %50'sinden fazlasından sorumlu değilse 50 veya daha fazla yüklemeye sahip tüm anahtarlar uygundur. 50'den az yüklemeye sahip anahtarları olan geliştiriciler gerekçe sunmalıdır.
50'den az yükleme 50 yükleme eşiğine hiçbir anahtar ulaşamamışsa ilk gelen kazanır mantığına göre herhangi bir anahtar kullanılabilir. Bir geliştirici kaydolduktan sonra diğerlerinin gerekçe sunması gerekir.

Anahtar sahipliğini doğrulama

API, mevcut bir paket adının doğrulamasını tamamlamak için bir doğrulama dizesi sağlar. Bu doğrulama dizesinin, uygulamanın öğeler klasöründeki adi-registration.properties adlı yeni bir dosyaya eklenmesi gerekir. Ardından, kaydettiğiniz ortak anahtara karşılık gelen özel anahtarı kullanarak APK'yı imzalayıp yüklemeniz gerekir.

Anahtar kaydını gerekçelendirme

Anahtar kaydı için gerekçe sunulması gerekiyorsa geliştiriciler ayrıntılı bir işletme gerekçesi sunmalıdır. Google bu gerekçeyi inceler ve paket adı kaydının onaylanması 24 saati bulabilir.

Kullanıcı deneyimiyle ilgili en iyi uygulamalar

Android Developer Console API'yi kullanan uygulamaların, sorunsuz bir entegrasyon için bu kalıpları izlemesi önerilir.

Net bir OAuth yetkilendirme bağlamı oluşturma

OAuth yetkilendirmesi istenmeden önce açık bir bağlam sağlanması, geliştiricilerin hesap erişiminin neden gerekli olduğunu anlamasına yardımcı olur. Kullanıcıları etkili bir şekilde yönlendirmek için OAuth kullanıcı rızası ekranını başlatmadan önce beklenen işlevle ilgili net bir açıklama sunun.

Yetkilendirme bağlamını aşağıdaki biçimi kullanarak yapılandırın:

  • Başlık: "Android Developer Console hesabınızı bağlayın"
  • Özet: "[application-name] uygulamasında Android geliştirici doğrulaması için paket adı kaydını yönetin"
  • İşlem düğmesi: "Google ile devam et" veya "Google ile oturum aç" düğmesi
Bir hesabı bağlamak için OAuth yetkilendirme bağlamını gösteren iletişim kutusu.
Şekil 1. Android Developer Console hesabınızı bağlayın.

Geliştirici hesaplarını tanımlama

  1. Erişim yetkisi verilmiş tüm geliştirici hesaplarını almak ve listelemek için ListDeveloperAccounts API yöntemiyle entegrasyon yapın.
  2. Geliştiricinin tercih ettiği geliştirici hesabını seçmesine olanak tanıyan bir hesap seçici sunun.
  3. displayName hesabını belirgin bir şekilde gösterin ve name alanındaki hesap numarasını ikincil bilgi olarak kullanın.
  4. Hesap doğrulama durumlarını görüntüleme (verificationState):
    • VERIFIED: Doğrulanmış geliştirici kimliğini olumlu bir görsel işaretle (ör. yeşil onay işareti) onaylayın.
    • NOT_VERIFIED: Doğrulamanın tamamlanmadığını belirtir ve hesabın paket kaydı yapmasını kısıtlar. İsteğe bağlı olarak, hesap seçildiğinde geliştiricileri Android Developer Console'a yönlendiren birincil bir harekete geçirici düğme ekleyin.
Geliştirici hesabı adını ve doğrulama durumunu gösteren hesap seçici.
Şekil 2. Geliştirici hesaplarını ve doğrulama durumunu gösteren hesap seçici.

Google Hesabı ile ilişkili geliştirici hesabı olmadığı için boş bir yanıt alınırsa geliştiricileri birincil harekete geçirici düğmeyi kullanarak Android Developer Console'a yönlendirin.

Paket adlarını yönetme

  1. Geliştirici hesabıyla ilişkili tüm paket adlarını almak için ListAndroidPackages API uç noktasıyla entegrasyon yapın. Geliştiricilere, paket durumlarını etkili bir şekilde izleyebilmeleri için liste veya tablo gibi merkezi bir arayüz sunun.
  2. packageName, mevcut kayıt durumuyla (DRAFT, IN_REVIEW, REGISTERED veya PENDING_TRANSFER) birlikte gösterilmeli ve her durum için farklı görsel göstergeler kullanılmalıdır. Oluşturma sırasında "kolay ad" sağlanıp kaydedildiyse isteğe bağlı olarak ekranda gösterilebilir.
Kayıtlı paket adlarını ve durumlarını gösteren arayüz.
Şekil 3. Paket adlarını ve kayıt durumlarını yönetmek için kullanılan arayüz.

Anahtarları yönetme

  1. Bir paket adına bağlı tüm anahtarları getirmek için ListAndroidPackageKeys API uç noktasını çağırın. Bu sayede geliştiriciler, kayıt durumlarını izlemek için yapılandırılmış bir genel bakış (ör. tablo veya liste) elde eder.
  2. Her anahtarın certificateFingerprintSha256 değerini, kayıt durumuyla (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE veya PENDING_TRANSFER) birlikte gösterin. Durumları ayırt etmek için farklı görsel göstergeler kullanın.
Sertifika parmak izlerinin ve anahtar kayıt durumlarının listesi.
Şekil 4. Anahtarlara ve kayıt durumlarına genel bakış.
  1. CreateAndroidPackageKey API yöntemiyle entegrasyon yaparak geliştiricilerin mevcut bir paket adı altında ek anahtarlar kaydetmesine olanak tanıyın.

Paket adı kaydetme

  1. Geliştiricilerin paket adlarını bir metin alanına girdiği form tabanlı bir düzen kullanın.Bu bilgilerin uygulamanız tarafından daha önce (ör. önceki bir istem aracılığıyla) toplanmamış olması gerekir.
  2. Geliştirici hesabına bir paket adı kaydetmek için CreateAndroidPackage API yöntemini, geçerli anahtar uygunluk kurallarını belirlemek için ise GetAndroidPackageRegistrationPolicy API yöntemini çağırın.
  3. Paket adı için belirlenen keySelectionStrategy uyarınca geliştiriciden aşağıdakilerden birini yapmasını isteyin:
    • keySelectionStrategy, SELECT_KEY_FROM_LIST olarak ayarlanmışsa: Geliştiricinin, sağlanan knownKeys listesinden (SHA-256 sertifika parmak izlerini içeren) kayıt için bir anahtar seçmesini sağlayın (ör. radyo düğmelerini kullanarak). Bu akış için anahtar sahipliği doğrulaması gerekir (aşağıdaki Anahtar sahipliğini doğrulama bölümüne bakın).
    • keySelectionStrategy, USE_ANY_KEY olarak ayarlanmışsa: Geliştiriciden doğrudan anahtar sağlamasını isteyin. Bu durumda anahtar sahipliği doğrulaması gerekmez.
  4. Seçilen anahtarı yeni paket adıyla ilişkilendirmek için CreateAndroidPackageKey API yöntemini çağırın.
Paket adını kaydetme ve imzalama anahtarını seçme formu.
Şekil 5. Paket adı kaydetme ve anahtar seçme akışı.

Alternatif olarak, uygulamanız paket adını veya anahtarı doğrudan yüklenen bir uygulamadan otomatik olarak algılayıp ayıklayabilir.

Anahtarın sahipliğini doğrulama

keySelectionStrategy, SELECT_KEY_FROM_LIST olarak ayarlandığında geliştiricilerin özel imzalama anahtarlarının sahipliğini kanıtlamaları gerekir. Sahiplik kanıtı için API tarafından oluşturulan verificationToken değerini içeren imzalı bir APK göndermeniz gerekir.

Anahtar sahipliği doğrulamasını desteklemek için VerifyAndroidPackageKeyOwnership API yöntemini entegre edin ve aşağıdaki kullanıcı arayüzü bileşenlerini oluşturun:

  • Jeton görüntüleme bileşeni: verificationToken değerini, kullanışlı bir "Panoya kopyala" düğmesiyle birlikte kod snippet'i bloğunda belirgin bir şekilde gösterin.
  • Geliştirici kurulum talimatları: Geliştiriciye, verificationToken içeren bir adi-registration.properties dosyasını uygulamanın öğeler klasörüne yerleştirmesini söyleyen ayrıntılı talimatlar verin.
  • APK gönderme bırakma bölgesi: İmzalı APK'yı almak için özel bir dosya yükleme bırakma bölgesi sunun.
Anahtar sahipliğini doğrulamak için bırakma bölgesi ve jeton ekranı.
Şekil 6. İmzalı APK yüklemesiyle anahtar sahipliğini doğrulamak için kullanıcı arayüzü bileşenleri.

Anahtar kaydını gerekçelendirme

Bilinen bir anahtarın justificationRequired alanı REQUIRED olarak ayarlandığında, geliştiricilerin bu anahtarı paket adıyla birlikte kaydetmek için kapsamlı bir işletme gerekçesi sunması gerekir.

Bu gerekçeyi JustifyAndroidPackageKeyRegistration API yöntemini çağırarak gönderin. Uygulamanızın kullanıcı arayüzünde, geliştiriciden gerekçeyi toplamak için özel bir metin giriş alanı bulunduğundan emin olun ve anahtar kaydı isteğini göndermeden önce gerekçe sunmanın zorunlu olduğunu geliştiriciye bildirin. Google, gönderilen gerekçeyi inceler. Paket adı kaydı tamamlanmadan önce onayın verilmesi 24 saati bulabilir.

Yönetilen anahtarlar için anahtar doğrulamasını otomatikleştirme

Uygulamanız bir geliştiricinin imzalama anahtarını yönetiyorsa geliştirici, sahiplik doğrulaması için APK'yı manuel olarak imzalayamaz. Bunun yerine, VerifyAndroidPackageKeyOwnership API çağrısını kullanıcılar adına otomatik olarak yürütmeniz gerekir.

Uygulamanız, jeton ekleme ve APK yükleme işlemlerini otomatik olarak gerçekleştirerek bu manuel adımları ortadan kaldırır. Geliştiricilere, anahtar sahipliği doğrulamasının sisteminizde depolanan anahtar kullanılarak uygulamanız tarafından sorunsuz bir şekilde yönetildiğini bildirin.

Marka kurallarına uyma

Kullanıcıların güvenini korumak ve şeffaflığı sağlamak için Android Developer Console API ile entegre olan tüm uygulamaların aşağıdaki marka kurallarına uyması gerekir.

Terminoloji ve büyük harf kullanımı

Kullanıcılara yönelik materyallerde veya dokümanlarda ürüne atıfta bulunurken her zaman Android Developer Console tam adını kullanın. "ADC" kısaltmasını kullanmayın.

Program, Android geliştirici doğrulaması olarak adlandırılmalıdır. Tüm bağlamlarda bu büyük harf kullanımını ve yazımı aynen uygulayın.

APK'lar veya AAB'lerle ilgili belirsizliği önlemek için yalnızca "paket" yerine "paket adı" terimini kullanın.

Paket adı ekleme sürecini açıklarken "paket adı talep etme" yerine "paket adı kaydetme" ifadesini kullanın.

"Oturum aç" harekete geçirici mesajını kullanma

Android Developer Console ile OAuth 2.0 kimlik doğrulaması, Google Kimlik Hizmetleri'ni kullanır. Google Kimlik Hizmetleri markalama kurallarına uymak için yetkilendirme düğmesinde "Google ile devam et" veya "Google ile oturum aç" harekete geçirici mesajını kullanmanız gerekir. Bu metin zorunludur ve değiştirilemez. Bu metin, kullanıcıların Google kimlik bilgilerini kullanarak uygulamanıza Google Hesaplarına erişim yetkisi verdiklerini anlamalarını sağlar.

Marka kimliğini ve bütünlüğünü koruma

Android Developer Console logosunu uygulama arayüzünüze entegre ederken görsel kimliği ve marka bütünlüğünü korumak için aşağıdaki spesifikasyonlara uymanız gerekir:

  • Logo yerleşimi ve hiyerarşisi: Yalnızca resmi, onaylı Android Developer Console logosunu kullanın. Uygulamanın resmi bir Google ürünü olarak yanlış tanıtılmasını önlemek için logo her zaman uygulamanızın kendi birincil marka öğelerinden sonra gelmelidir.
Resmi Android Developer Console logosu. Dosyayı kaydetmek için tıklayın.
Şekil 7. Resmi Android Developer Console logosu. Dosyayı kaydetmek için resmi tıklayın.
  • Görsel stil ve bozulmalar: Öğe her zaman en boy oranı tamamen kısıtlanmış şekilde oluşturulmalıdır. Logonun bileşenlerini hiçbir zaman bozmamalı, uzatmamalı, eğmemeli, kırpmamalı, çevirmemeli veya değiştirmemelisiniz. Resmi renk paletini değiştirmeyin, ön plan veya arka plan renklerini değiştirmeyin ya da gölge, parlama efektleri veya dekoratif gradyanlar uygulamayın.
  • Kullanım kısıtlamaları: Google'a ait marka öğelerini kendi uygulama öğelerinize dahil etmeyin. Android Developer Console logo öğesi, yalnızca etkin bir entegrasyonu açıkça belirtmek için uygulama düzeni bağlamında kullanılabilir.

Ek kaynaklar