Uyumluluk çerçevesi araçları

Android 11, uygulamanızı Android platformunun yeni sürümlerindeki davranış değişikliklerine göre test etmek ve hata ayıklamak için yeni geliştirici araçlarını kullanıma sundu. Bu araçlar, uygulama geliştiricilerin geliştirici seçeneklerini veya ADB'yi kullanarak önemli değişiklikleri ayrı ayrı açıp kapatmalarına olanak tanıyan bir uyumluluk çerçevesinin parçasıdır. En son kararlı API sürümünü hedeflemeye hazırlanırken ve uygulamanızı bir sonraki Android sürümünün önizleme sürümüyle test ederken bu esnekliği kullanın.

Uyumluluk çerçevesi araçlarını kullandığınızda Android platformu, dahili mantığını otomatik olarak uyarlar. Böylece temel testler gerçekleştirmek için targetSDKVersion öğenizi değiştirmeniz veya uygulamanızı yeniden derlemeniz gerekmez. Değişiklikler tek tek değiştirilebildiğinden, her defasında bir davranış değişikliğini yalıtabilir, test edebilir ve hata ayıklayabilirsiniz veya önce başka bir şeyi test etmeniz gerekiyorsa sorunlara neden olan tek bir değişikliği devre dışı bırakabilirsiniz.

Hangi değişikliklerin etkinleştirildiğini belirleme

Bir davranış değişikliği etkinleştirildiğinde, uygulamanızın bu değişiklikten etkilenen platform API'lerine erişimi etkilenebilir. Geliştirici seçeneklerini, logcat veya ADB komutlarını kullanarak hangi davranış değişikliklerinin etkinleştirildiğini kontrol edebilirsiniz.

Geliştirici seçeneklerini kullanarak etkin değişiklikleri belirleme

Şekil 1. Uygulama Uyumluluğu Değişiklikleri ekranında görünür.

Cihazın geliştirici seçeneklerinde hangi değişikliklerin etkinleştirildiğini görebilir ve bu değişiklikleri açıp kapatabilirsiniz. Bu seçeneklere erişmek için aşağıdaki adımları uygulayın:

  1. Geliştirici seçenekleri henüz etkin değilse bunları etkinleştirin.
  2. Cihazınızın Ayarlar uygulamasını açıp Sistem > Gelişmiş > Geliştirici seçenekleri > Uygulama Uyumluluğu Değişiklikleri'ne gidin.
  3. Listeden uygulamanızı seçin.

Her davranış değişikliği genellikle aşağıdaki iki kategoriden birine aittir:

  • Uygulamanın targetSdkVersion ürününden bağımsız olarak, Android'in ilgili sürümünde çalışan tüm uygulamaları etkileyen değişiklikler.

    Bu değişiklikler, uyumluluk çerçevesinde varsayılan olarak etkinleştirilir ve kullanıcı arayüzündeki Varsayılan Etkin Değişiklikler bölümünde listelenir.

  • Yalnızca belirli Android sürümlerini hedefleyen uygulamaları etkileyen değişiklikler. Bu değişiklikler yalnızca Android'in belirli bir sürümünü hedefleyen uygulamaları etkilediğinden, targetSDKVersion tarafından korunan değişiklikler olarak da adlandırılır.

    Uygulamanız listelenen API sürümünden daha yüksek bir sürümü hedefliyorsa bu değişiklikler, uyumluluk çerçevesinde varsayılan olarak etkindir. Örneğin, Android 13'te (API düzeyi 33) targetSDKVersion tarafından korunan bir davranış değişikliği, kullanıcı arayüzünde Enabled for targetSdkVersion >=33 başlıklı bir bölüm olarak listelenir. Android'in bazı daha eski sürümlerinde bu bölümün başlığı "API_LEVEL SDK'sından Sonra Etkinleştirildi" şeklindedir.

Ayrıca, şekil 1'de Varsayılan Devre Dışı Bırakılan Değişiklikler adlı bir bölüm de göreceksiniz. Bu bölüme giren değişiklikler çeşitli amaçlara hizmet edebilir. Bu değişiklikleri etkinleştirmeden önce, söz konusu Android sürümünün uyumluluk çerçevesi listesindeki değişiklik açıklamasını okuyun.

Logcat'i kullanarak etkin değişiklikleri belirleme

Her davranış değişikliği için, uygulamanızın işlemi sırasında uygulamanız etkilenen API'yi ilk kez çağırdığında sistem şuna benzer bir logcat mesajı verir:

D CompatibilityChangeReporter: Compat change id reported: 194833441; UID 10265; state: ENABLED

Her logcat iletisi aşağıdaki bilgileri içerir:

Değişiklik Kimliği
Uygulamayı etkileyen değişikliği gösterir. Bu değer, Uygulama Uyumluluğu Değişiklikleri ekranında listelenen davranış değişikliklerinden biriyle eşleşir (şekil 1'e bakın). Bu örnekte 194833441, NOTIFICATION_PERM_CHANGE_ID ile eşlenir.
Benzersiz Kimlik
Değişiklikten hangi uygulamanın etkilendiğini belirtir.
Eyalet

Değişikliğin uygulamayı etkileyip etkilemediğini belirtir.

Eyalet, şu değerlerden biri olabilir:

Eyalet Anlamı
ENABLED Değişiklik etkinleştirilir ve uygulama, değiştirilen API'leri kullanıyorsa uygulamanın davranışını etkiler.
DISABLED

Değişiklik devre dışı bırakıldı ve uygulamayı etkilemeyecek.

Not: Uygulamanın targetSDKVersion değeri gerekli eşiğin altında olduğu için bu değişiklik devre dışı bırakılırsa uygulama daha yüksek bir sürümü hedeflemek için targetSDKVersion değerini artırdığında değişiklik varsayılan olarak etkinleştirilir.

LOGGED Değişiklik, uyumluluk çerçevesi üzerinden günlüğe kaydedilmektedir ancak açılamaz veya kapatılamaz. Bu değişiklik, açıp kapatılamasa da uygulamanızın davranışını etkileyebilir. Daha fazla bilgi için ilgili Android sürümünün uyumluluk çerçevesi listesindeki değişikliğin açıklamasına bakın. Çoğu durumda bu tür değişiklikler deneme amaçlıdır ve göz ardı edilebilir.

ADB kullanarak etkin değişiklikleri belirleme

Cihazın tamamında yapılan değişikliklerin (hem etkin hem de devre dışı) tamamını görmek için aşağıdaki ADB komutunu çalıştırın:

adb shell dumpsys platform_compat

Çıkış, her değişiklik için aşağıdaki bilgileri listeler:

Değişiklik Kimliği
Bu davranış değişikliğinin benzersiz tanımlayıcısı. Örneğin, 194833441.
Ad
Bu davranış değişikliğinin adı. Örneğin, NOTIFICATION_PERM_CHANGE_ID.
targetSDKVersion ölçütleri

Değişikliğin hangi targetSDKVersion tarafından korunduğu (varsa).

Örneğin, bu değişiklik yalnızca SDK 33 veya sonraki sürümleri hedefleyen uygulamalar için etkinleştirilirse enableAfterTargetSdk=32 çıkışı yapılır. Değişiklik targetSDKVersion tarafından kontrol edilmezse enableAfterTargetSdk=0 çıkış olur.

Paket geçersiz kılmaları

Değişikliğin varsayılan durumunun (etkin veya devre dışı) geçersiz kılındığı her paketin adı.

Örneğin, bu varsayılan olarak etkinleştirilen bir değişiklikse geliştirici seçeneklerini veya ADB'yi kullanarak değişikliği kapatmanız durumunda uygulamanızın paket adı listelenir. Bu durumda, çıktı aşağıdaki gibi olur:

packageOverrides={com.my.package=false}

targetSDKVersion tarafından korunan değişiklikler varsayılan olarak etkinleştirilebilir veya devre dışı bırakılabilir. Böylece paket listesi, her bir uygulamanın targetSDKVersion öğesine bağlı olarak true veya false örneklerini içerebilir. Örneğin:

packageOverrides={com.my.package=true, com.another.package=false}

Belirli değişiklikler hakkında daha fazla bilgi

Uyumluluk çerçevesindeki davranış değişikliklerinin tam listesi, her Android sürümünün belgelerinde yer almaktadır. Uygulamanızı test ettiğiniz Android sürümüne bağlı olarak daha fazla bilgi için aşağıdaki bağlantılara bakın:

Değişiklikler ne zaman açılır/kapatılır

Uyumluluk çerçevesinin ana amacı, uygulamanızı Android'in yeni sürümleriyle test ederken size kontrol ve esneklik sağlamaktır. Bu bölümde, uygulamanızı test ederken ve hata ayıklarken değişiklikleri ne zaman açıp kapatacağınızı belirlemek için kullanabileceğiniz bazı stratejiler açıklanmaktadır.

Değişiklikler ne zaman kapatılır?

Değişikliklerin ne zaman açılıp kapatılacağına karar vermek genellikle değişikliğin targetSDKVersion tarafından engellenip engellenmediğine bağlıdır.

Değişiklikler tüm uygulamalar için etkinleştirildi

Tüm uygulamaları etkileyen değişiklikler, uygulamanızın targetSDKVersion sürümünden bağımsız olarak belirli bir platform sürümü için varsayılan olarak etkinleştirilir. Böylece, uygulamanızın bu platform sürümünde çalıştırılmasından etkilenip etkilenmediğini görebilirsiniz.

Örneğin, Android 14'ü (API düzeyi 34) hedeflemeye hazırlanıyorsanız uygulamanızı Android 14 çalıştıran bir cihaza yükleyerek başlayabilir ve tipik test iş akışlarınızı kullanarak uygulamanızı test edebilirsiniz. Uygulamanızda sorunlarla karşılaşırsanız soruna neden olan değişikliği devre dışı bırakarak diğer sorunları test etmeye devam edebilirsiniz.

Bu değişiklikler, targetSDKVersion sürümünden bağımsız olarak tüm uygulamaları etkileyebileceğinden, genellikle uygulamanızı targetSDKVersion tarafından korunan değişikliklerden önce bu değişikliklere göre test etmeniz ve güncellemeniz gerekir. Bu, kullanıcılarınızın cihazlarını yeni bir platform sürümüne güncellediklerinde uygulama deneyiminin kalitesini düşürmelerine yardımcı olur.

Ayrıca, Android'in herkese açık sürüm derlemesini kullanırken bu değişiklikleri devre dışı bırakamayacağınız için bu değişiklikleri test etmeye öncelik vermelisiniz. İdeal olarak, bir sürüm önizlemedayken Android'in her bir sürümü için bu değişiklikleri test etmeniz gerekir.

targetSDKVersion tarafından korunan değişiklikler

Uygulamanız belirli bir targetSDKVersion öğesini hedefliyorsa bu sürüm tarafından korunan tüm değişiklikler varsayılan olarak etkinleştirilir. Dolayısıyla, uygulamanızın targetSDKVersion değerini yeni bir sürüme geçirdiğinizde uygulamanız aynı anda birçok yeni değişiklikten etkilenmeye başlar.

Uygulamanız bu değişikliklerden birden fazlasından etkilenebilir. Bu nedenle, uygulamanızı test ederken ve hata ayıklarken bu değişikliklerden bazılarını ayrı ayrı kapatmanız gerekebilir.

Değişiklikler ne zaman açılır?

Bir uygulama, güvenli sürümden daha düşük bir SDK sürümünü hedeflediğinde belirli bir targetSDKVersion tarafından korunan değişiklikler varsayılan olarak devre dışı bırakılır. Genellikle, yeni bir targetSdkVersion için hedefleme yapmaya hazırlanırken uygulamanızı test edip hata ayıklama yapmanız gereken davranış değişikliklerinin bir listesini görürsünüz.

Örneğin, önümüzdeki targetSdkVersion gün içinde uygulamanızı bir dizi platform değişikliğine karşı test ediyor olabilirsiniz. Uygulama manifestinizi değiştirip tüm değişiklikleri tek seferde etkinleştirmek yerine, geliştirici seçeneklerini veya ADB komutlarını kullanarak korunan her değişikliği tek tek etkinleştirip test edebilirsiniz. Bu ek kontrol, değişiklikleri izole olarak test etmenize yardımcı olabilir ve aynı anda uygulamanızın birden fazla bölümünü hata ayıklamaktan ve güncellemekten kaçınmanıza yardımcı olabilir.

Bir değişikliği etkinleştirdikten sonra tipik test iş akışlarınızı kullanarak uygulamanızı test edebilir ve hatalarını ayıklayabilirsiniz. Sorunlarla karşılaşırsanız sorunun nedenini belirlemeye yardımcı olması için günlüklerinizi kontrol edin. Sorunun, etkinleştirilmiş bir platform değişikliğinden kaynaklanıp kaynaklanmadığından emin olamıyorsanız, bu değişikliği devre dışı bırakmayı deneyin ve ardından uygulamanızın söz konusu alanını yeniden test edin.

Değişiklikleri aç veya kapat

Uyumluluk çerçevesi, geliştirici seçeneklerini veya ADB komutlarını kullanarak her bir değişikliği açmanıza veya kapatmanıza olanak tanır. Değişikliklerin açılıp kapatılması uygulamanızın kilitlenmesine veya önemli güvenlik değişikliklerini devre dışı bırakmasına neden olabileceğinden, değişiklikleri ne zaman değiştirebileceğinizle ilgili bazı kısıtlamalar bulunur.

Geliştirici seçeneklerini kullanarak değişiklikleri açma/kapatma

Değişiklikleri açıp kapatmak için geliştirici seçeneklerini kullanın. Geliştirici seçeneklerini bulmak için şu adımları izleyin:

  1. Geliştirici seçenekleri henüz etkin değilse bunları etkinleştirin.
  2. Cihazınızın Ayarlar uygulamasını açıp Sistem > Gelişmiş > Geliştirici seçenekleri > Uygulama Uyumluluğu Değişiklikleri'ne gidin.
  3. Listeden uygulamanızı seçin.
  4. Değişiklikler listesinde, etkinleştirmek veya devre dışı bırakmak istediğiniz değişikliği bulun ve anahtara dokunun.

    Açılıp kapatılabilen değişikliklerin listesi

ADB kullanarak değişiklikleri aç/kapat

ADB'yi kullanarak bir değişikliği açmak veya kapatmak için aşağıdaki komutlardan birini çalıştırın:

adb shell am compat enable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
adb shell am compat disable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

CHANGE_ID (örneğin, 194833441) veya CHANGE_NAME (örneğin, NOTIFICATION_PERM_CHANGE_ID) ve uygulamanızın PACKAGE_NAME kodunu iletin.

Bir değişikliği varsayılan durumuna sıfırlamak, ADB veya geliştirici seçeneklerini kullanarak ayarladığınız geçersiz kılmaları kaldırmak için aşağıdaki komutu da kullanabilirsiniz:

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Değişiklikleri açıp kapatmayla ilgili kısıtlamalar

Varsayılan olarak, her davranış değişikliği etkinleştirilir veya devre dışı bırakılır. Tüm uygulamaları etkileyen değişiklikler varsayılan olarak etkinleştirilir. Diğer değişiklikler bir targetSdkVersion ile kontrol edilir. Bu değişiklikler, bir uygulama karşılık gelen SDK sürümünü veya sonraki bir sürümü hedeflediğinde varsayılan olarak etkinleştirilir, güvenli sürümden daha düşük bir SDK sürümünü hedeflediğinde ise varsayılan olarak devre dışı bırakılır. Bir değişikliği açtığınızda veya kapattığınızda varsayılan durumunu geçersiz kılarsınız.

Uyumluluk çerçevesinin kötü amaçlı olarak kullanılmasını önlemek için değişiklikleri ne zaman değiştirebileceğinizle ilgili bazı kısıtlamalar vardır. Bir değişikliği açıp açamayacağınız, değişikliğin türüne, uygulamanızın hata ayıklamaya uygun olup olmadığına ve cihazınızda çalıştırılmakta olan derleme türüne bağlıdır. Aşağıdaki tabloda, farklı değişiklik türlerini ne zaman açabileceğiniz açıklanmaktadır:

Derleme türü Hata ayıklaması mümkün olmayan uygulama Hata ayıklanabilir uygulama
Tüm değişiklikler targetSDKVersion tarafından korunan değişiklikler Diğer tüm değişiklikler
Geliştirici Önizlemesi veya Beta yapısı Geçiş yapılamıyor Geçiş yapabilir Geçiş yapabilir
Herkese açık kullanıcı derlemesi Geçiş yapılamıyor Geçiş yapabilir Geçiş yapılamıyor