Android Developer Console API ile paket adlarını kaydetme

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

Şu rollerde sunucudan sunucuya özellikleriniz:

Uygulama dağıtımcısı Bireysel geliştirici
Mağazada uygulama yayınlayan geliştirici adına paket adı ve anahtar kaydetme Mağaza tarafından yönetilen bir anahtarla paket adı kaydetme Bir paket adıyla ilişkili anahtarın sahipliğini kanıtlayın. Paket adı kaydetme: Sürekli dağıtım iş akışlarınızda anahtar rol oynar. Bir paket adıyla ilişkili anahtarın sahipliğini 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ğıdaki konularda temel bilgi sahibi olmanız gerekir:

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ı içindeki belirli bir Android paket adı (ör. com.example.app), bir veya daha fazla anahtarla ilişkilendirilebilir. Kayıt durumu (DRAFT, IN_REVIEW, REGISTERED veya PENDING_TRANSFER) içerir.
Anahtar Bir Android paket adını imzalamak için kullanılan 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 API'yi seçerek API'nin genel bakış sayfasına gidin.
    2. Mavi Etkinleştir düğmesini tıklayın. Google Cloud, seçtiğiniz proje için API'yi etkinleştirir. Bu işlem genellikle yalnızca bir an sürer. Etkinleştirdikten 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 projesi yerine 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

Android Developer Console API ile entegrasyon için uygulamaların 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 (önerilir): Ç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) arka planda kullanıcı müdahalesi olmadan çalışmasına olanak tanır:

Tek seferlik kullanıcı izni kurulumu: İlk kurulum sırasında bir geliştirici veya hesap sahibi, tarayıcısında tek seferlik bir izin akışını tamamlar. Uygulamanız, API kapsamıyla birlikte çevrimdışı erişim (access_type=offline) isteğinde bulunuyor. 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 öğesini dağıtım ortamınızda veya gizli anahtar yöneticinizde (örneğin, GitHub Actions Secrets, Google Secret Manager) güvenli bir şekilde saklayın. Sonraki API çağrıları için otomatik iş akışınız, depolanan yenileme jetonunu kullanarak isteğe bağlı olarak yeni ve kısa ömürlü bir erişim jetonu alır. Böylece, manuel giriş veya 2FA istemleri atlanır. 		Ortamınızda uzun süreli yenileme jetonlarını 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 istem: Ç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ı oturum açar ve izin verir. 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 atılır. 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. Bir anahtarın nasıl kaydedileceği, Android'de yeni veya mevcut bir paket adına anahtar kaydedip kaydetmediğ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, kayıt için uygun olan 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 yine de kaydedebilirsiniz ancak sahipliği kanıtlayan belgeyi sunmanın yanı sıra geliştiricinin 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ştiriciler gerekçe sunmalıdır.
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ğrulanmasını tamamlamak için doğrulama dizesi sağlar. Bu doğrulama dizesi, uygulamanın öğe klasöründe adi-registration.properties adlı yeni bir dosyanın içine eklenmelidir. Ardından, kaydettirdiğiniz ortak anahtara karşılık gelen özel anahtarı kullanarak APK'yı imzalamanız ve yüklemeniz gerekir.

Anahtar kaydını gerekçelendirme

Önemli bir kayıt için gerekçe sunulması gerekiyorsa geliştiriciler ayrıntılı bir ticari gerekçe göndermelidir. Google bu gerekçeyi inceler ve paket adı kaydı için onay süreci 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şturun

OAuth yetkilendirmesi istemeden önce açık bir bağlam sağlamak, geliştiricilerin hesap erişiminin neden gerekli olduğunu anlamalarına yardımcı olur. Kullanıcılara etkili bir şekilde rehberlik etmek 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çimde yapılandırın:

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

Geliştirici hesaplarını tanımlama

  1. Erişimin yetkilendirildiği tüm geliştirici hesaplarını almak ve listelemek için ListDeveloperAccounts API yöntemiyle entegre edin.
  2. Geliştiricinin tercih ettiği geliştirici hesabını seçmesine olanak tanıyan bir hesap seçici sağlayın.
  3. name alanındaki hesap numarasını ikincil bilgi olarak kullanarak hesabı displayName öne çıkarın.
  4. Hesap doğrulama durumlarını görüntüleme (verificationState):
    • VERIFIED: Doğrulanmış geliştirici kimliğini olumlu bir görsel ipucuyla (ör. yeşil onay işareti) onaylayın.
    • NOT_VERIFIED: Doğrulamanın tamamlanmadığını belirtin ve hesap için paket kaydını kısıtlayın. İsteğe bağlı olarak, hesabı seçtikten sonra geliştiricileri Android Developer Console'a yönlendiren birincil bir harekete geçirici mesaj düğmesi sağlayın.
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şkilendirilmiş geliştirici hesabı olmadığı için boş bir yanıt alınırsa birincil bir harekete geçirici mesaj düğmesi kullanarak geliştiricileri 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 entegre edin. Geliştiricilere, paket durumlarını etkili bir şekilde izlemeleri için liste veya tablo gibi merkezi bir arayüz sunar.
  2. packageName simgesini mevcut kayıt durumuyla (DRAFT, IN_REVIEW, REGISTERED veya PENDING_TRANSFER) birlikte gösterin. Her durum için farklı görsel göstergeler kullanın. Oluşturma sırasında "kolay ad" sağlanıp kaydedilmişse bunu isteğe bağlı olarak ekleyebilirsiniz.
Kayıtlı paket adlarını ve durumlarını gösteren arayüz.
Şekil 3. Paket adlarını ve kayıt durumlarını yönetme arayüzü.

Anahtarları yönetme

  1. Bir paket adıyla ilişkili tüm anahtarları getirmek için ListAndroidPackageKeys API uç noktasını çağırın. Bu sayede geliştiricilere, kayıt durumlarını izlemeleri için yapılandırılmış bir genel bakış (ör. tablo veya liste) sunulur.
  2. Her anahtar için certificateFingerprintSha256 simgesini, 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 kaydı 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. Bu bilgiler uygulamanız tarafından daha önce toplanmadıysa (ör. önceki bir istem aracılığıyla) geliştiricilerin paket adlarını bir metin alanına girdiği form tabanlı bir düzen kullanın.
  2. Bir paket adını geliştirici hesabına 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 temelinde, 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çerir) kaydetmek için bir anahtar seçmesini sağlayın. Örneğin, radyo düğmelerini kullanabilir. 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 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'yı 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 simgesini, "Panoya Kopyala" düğmesi de dahil olmak üzere bir kod snippet'i bloğunda belirgin bir şekilde gösterin.
  • Geliştirici kurulum talimatları: Geliştiriciyi, adi-registration.properties dosyasını verificationTokenuygulamanın öğeler klasörüne yerleştirmeye yönlendiren ayrıntılı talimatlar sağlayın.
  • APK gönderim alanı: İmzalı APK'yı almak için özel bir dosya yükleme alanı sunun.
Anahtar sahipliğini doğrulamak için bırakma alanı ve jeton gösterimi.
Şekil 6. İmzalı APK yükleme ile anahtar sahipliğini doğrulama için kullanıcı arayüzü bileşenleri.

Anahtar kaydını gerekçelendirme

Bilinen bir anahtarın justificationRequired alanı REQUIRED olarak ayarlandığında, bu anahtarın paket adıyla birlikte kaydedilmesi için geliştiricilerin ayrıntılı bir işletme gerekçesi göndermesi gerekir.

JustifyAndroidPackageKeyRegistration API yöntemini çağırarak bu gerekçeyi gönderin. Uygulamanızın kullanıcı arayüzünde, geliştiriciden gerekçeyi almak için özel bir metin girişi alanı bulunduğundan emin olun ve geliştiriciye, anahtar kaydı isteğini göndermeden önce gerekçe sağlamanın zorunlu olduğunu bildirin. Google, gönderilen gerekçeyi inceler. Bu inceleme, paket adı kaydı tamamlanmadan önce 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 bir APK'yı manuel olarak imzalayamaz. Bunun yerine, VerifyAndroidPackageKeyOwnership API çağrısını onlar adına otomatik olarak yürütmeniz gerekir.

Uygulamanız, jeton ekleme ve APK yükleme sürecini otomatik olarak yöneterek bu manuel adımları ortadan kaldırır. Geliştiricileri, anahtar sahipliği doğrulamasının sisteminizde depolanan anahtar kullanılarak uygulamanız tarafından sorunsuz bir şekilde yönetildiği konusunda bilgilendirin.

Markalama kurallarına uyun

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ı

Ürüne kullanıcıya yönelik materyallerde veya dokümanlarda atıfta bulunurken her zaman Android Developer Console'un 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 büyük harf kullanımına ve yazıma dikkat edin.

APK'lar veya AAB'lerle ilgili belirsizliği önlemek için "paket" yerine özellikle "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'ne dayanır. Google Kimlik Hizmetleri markalama yönergelerine uygun kalmak 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. Kullanıcıların, Google Hesaplarına erişmek için uygulamanızı yetkilendirirken Google kimlik bilgilerini kullandıklarını 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 özellikleri kullanmanız gerekir:

  • Logo yerleşimi ve hiyerarşi: Yalnızca resmi ve onaylı Android Developer Console logosunu kullanın. Uygulamanın resmi bir Google ürünü olarak yanlış tanıtılmasını önlemek için logo, uygulamanızın birincil marka öğelerinin her zaman ikincil öğesi olmalıdır.
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: Öğenin en boy oranı her zaman tam olarak kısıtlanmış şekilde oluşturulmalıdır. Logonun bileşenlerini hiçbir zaman bozmamalı, genişletmemeli, eğmemeli, kırpmamalı, ters çevirmemeli veya değiştirmemelisiniz. Resmi renk paletini değiştirmeyin, ön veya arka plan renklerini değiştirmeyin ya da gölge, parlama efektleri veya dekoratif renk geçişleri uygulamayın.
  • Kullanım kısıtlamaları: Google'a ait marka öğelerini kendi uygulama öğelerinize dahil etmeyin. Android Developer Console logo öğesi yalnızca uygulama düzeni bağlamında etkin bir entegrasyonu açıkça belirtmek için kullanılabilir.

Ek kaynaklar