Google Play Uygulama İmzalama: Yükleme Anahtarı, Play App Signing ve Flutter Rehberi

Google Play'e uygulama yüklerken karşınıza çıkan "uygulama imzalama anahtarı", "yükleme anahtarı" ve "Play uygulama imzalama" kavramları ilk seferde kafa karıştırıcıdır. Bu rehberde Google Play'de uygulama imzalamanın nasıl çalıştığını, anahtarınızı nasıl oluşturacağınızı, Flutter ve Android Studio'da nasıl yapılandıracağınızı ve anahtarı kaybederseniz ne yapacağınızı anlatıyoruz.

Önce önemli bir not: Android için CA sertifikası gerekmez

Android uygulamaları, Windows programlarından farklı olarak bir sertifika otoritesinden (CA) satın alınan kod imzalama sertifikasıyla imzalanmaz. Android'de imza, sizin oluşturduğunuz bir anahtarla yapılır ve güven Google Play tarafından sağlanır. Yani Google Play'de uygulama yayınlamak için sertifika satın almanız gerekmez. Aynı uygulamanın Windows masaüstü sürümünü dağıtıyorsanız, o sürüm için kod imzalama sertifikası gerekir (yazının sonuna bakın).

İki anahtar: uygulama imzalama anahtarı ve yükleme anahtarı

Bu yapının adı Play Uygulama İmzalamadır (Play App Signing). Ağustos 2021'den bu yana Google Play'e eklenen yeni uygulamalar Android App Bundle (AAB) formatında yüklenmek ve Play Uygulama İmzalama'yı kullanmak zorundadır. En büyük avantajı: yükleme anahtarınızı kaybederseniz uygulamanızı kaybetmezsiniz, anahtarı sıfırlatabilirsiniz.

Adım 1: Yükleme anahtarını (keystore) oluşturun

JDK ile gelen keytool aracını kullanın:

keytool -genkeypair -v -keystore upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload

Araç sizden keystore şifresi, anahtar şifresi ve ad/şirket bilgilerini ister. Bu bilgiler kullanıcılara gösterilmez ama şifreleri ve .jks dosyasını mutlaka güvenli bir yere yedekleyin. Android Studio kullanıyorsanız aynı işlemi Build → Generate Signed Bundle / APK menüsündeki sihirbazla da yapabilirsiniz.

Adım 2: Flutter projesinde imzalamayı yapılandırın

1) android/key.properties dosyasını oluşturun ve bu dosyayı Git'e eklemeyin:

storePassword=KEYSTORE_SIFRESI
keyPassword=ANAHTAR_SIFRESI
keyAlias=upload
storeFile=C:/anahtarlar/upload-keystore.jks

2) android/app/build.gradle dosyasında imzalama ayarını ekleyin (Groovy):

def keystoreProperties = new Properties()
def keystorePropertiesFile = rootProject.file('key.properties')
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
}

android {
    signingConfigs {
        release {
            keyAlias keystoreProperties['keyAlias']
            keyPassword keystoreProperties['keyPassword']
            storeFile keystoreProperties['storeFile'] ? file(keystoreProperties['storeFile']) : null
            storePassword keystoreProperties['storePassword']
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

Yeni Flutter projeleri build.gradle.kts (Kotlin DSL) kullanır; mantık aynıdır, yalnızca söz dizimi farklıdır. Flutter'a özel ayrıntılar için Flutter ve Dart'ta imzalama yazımıza bakabilirsiniz.

3) Yayın paketini oluşturun:

flutter build appbundle --release

Çıktı build/app/outputs/bundle/release/app-release.aab konumundadır.

Adım 3: Play Console'da Play Uygulama İmzalama'yı etkinleştirin

1. Play Console'da uygulamanızı açın.
2. İlk sürümü oluştururken Google, Play Uygulama İmzalama'yı kullanmanızı ister. Önerilen seçenekle devam ederseniz uygulama imzalama anahtarını Google oluşturur.
3. İmzaladığınız .aab dosyasını yükleyin. Bu ilk yükleme, yükleme anahtarınızı Google'a tanıtır.
4. Anahtar bilgilerini daha sonra "Uygulama bütünlüğü" (App integrity) sayfasındaki Play uygulama imzalama bölümünde görebilirsiniz.

Firebase ve Google ile Giriş için SHA-1 / SHA-256 parmak izleri

Uygulamanız Play Store'dan indirildiğinde Google Giriş, Firebase veya Google Haritalar çalışmıyorsa sebep genellikle yanlış parmak izidir. Play'den inen uygulamalar Google'ın uygulama imzalama anahtarıyla imzalanır, sizin yükleme anahtarınızla değil.

Çözüm: Play Console'da Uygulama bütünlüğü → Play uygulama imzalama sayfasından uygulama imzalama anahtarı sertifikasının SHA-1 ve SHA-256 değerlerini kopyalayıp Firebase/Google Cloud projenize ekleyin. Yerel testler için yükleme anahtarınızın parmak izini de ekleyebilirsiniz:

keytool -list -v -keystore upload-keystore.jks -alias upload

Yükleme anahtarını kaybettim, ne yapmalıyım?

Play Uygulama İmzalama kullanıyorsanız uygulamanız kurtarılabilir:

1. Yukarıdaki komutla yeni bir yükleme anahtarı oluşturun.
2. Play Console'da Uygulama bütünlüğü sayfasından yükleme anahtarı sıfırlama talebi gönderin ve yeni anahtarın sertifikasını (PEM) ekleyin.
3. Google talebi onayladıktan sonra yeni anahtarla yükleme yapabilirsiniz.

Play Uygulama İmzalama'ya geçmemiş çok eski bir uygulamanın imzalama anahtarını kaybettiyseniz, maalesef uygulamayı güncelleyemezsiniz; yeni bir paket adıyla yayınlamanız gerekir. Bu yüzden anahtar yedeklemesi çok önemlidir.

Sık yapılan hatalar

• Keystore dosyasını veya key.properties'i Git'e eklemek: Anahtarınız başkalarının eline geçebilir. .gitignore'a ekleyin.
• Debug anahtarıyla yayın paketi üretmek: Play Console bu paketi reddeder.
• Farklı bir yükleme anahtarıyla paket yüklemek: "Uygulama paketiniz yanlış anahtarla imzalanmış" hatası alırsınız; Play Console'un beklediği yükleme anahtarının parmak izi hata mesajında yazar.
• Anahtar şifresini unutmak: Şifreyi bir parola yöneticisinde saklayın.

APK dosyasını Play dışında dağıtıyorsanız ve keystore yönetimini daha ayrıntılı öğrenmek istiyorsanız Android APK imzalama rehberimize göz atın.

Uygulamanızın Windows sürümü de varsa

Flutter veya başka bir çapraz platform araçla Windows masaüstü sürümü de dağıtıyorsanız, o sürüm için durum farklıdır. İmzasız bir Windows kurulum dosyası kullanıcılarınızda "Windows kişisel bilgisayarınızı korudu" uyarısı gösterir. Windows sürümünü bir kod imzalama sertifikası ile imzalamanız gerekir; bulutta imzalama yapabileceğiniz seçenekler için Cloud kod imzalama sayfamıza bakabilirsiniz.

Sıkça Sorulan Sorular

Google Play'de uygulama yayınlamak için sertifika satın almam gerekir mi?

Hayır. Android uygulamaları kendi oluşturduğunuz anahtarla imzalanır; Play Uygulama İmzalama kullandığınızda son imzayı Google atar. Sertifika satın almanız yalnızca Windows, macOS veya Java gibi platformlarda dağıttığınız sürümler için gerekir.

Uygulama imzalama anahtarını kendim yükleyebilir miyim?

Evet. Uygulamayı daha önce Play dışında kendi anahtarınızla dağıttıysanız, mevcut imzalama anahtarınızı Play Console'un sunduğu araçla şifreli olarak Google'a yükleyebilirsiniz. Böylece Play'den gelen güncellemeler mevcut kurulumların üzerine sorunsuz yüklenir.

Yükleme anahtarının geçerlilik süresi ne kadar olmalı?

Google en az 25 yıl önerir. Yukarıdaki komuttaki -validity 10000 değeri yaklaşık 27 yıldır.