Uyumluluk çerçevesi araçları

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

Uyumluluk çerçevesi araçlarını kullandığınızda Android platformu dahili mantığını otomatik olarak uyarlar. Bu nedenle, temel testleri gerçekleştirmek için targetSDKVersion'nizi değiştirmeniz veya uygulamanızı yeniden derlemeniz gerekmez. Değişiklikler tek tek etkinleştirilip devre dışı bırakılabildiğinden, tek seferde bir davranış değişikliğini ayırıp test edebilir ve hata ayıklayabilir veya önce başka bir şeyi test etmeniz gerekiyorsa soruna 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şme şekli etkilenebilir. Geliştirici seçeneklerini, logcat'i veya ADB komutlarını kullanarak hangi davranış değişikliklerinin etkinleştirildiğini kontrol edebilirsiniz.

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

Şekil 1. Geliştirici seçeneklerindeki Uygulama Uyumluluğuyla İlgili Değişiklikler ekranı.

Hangi değişikliklerin etkin olduğunu görebilir ve cihazın geliştirici seçeneklerinde bu değişiklikleri etkinleştirebilir veya devre dışı bırakabilirsiniz. Bu seçeneklere erişmek için aşağıdaki adımları uygulayın:

1. Geliştirici seçenekleri etkinleştirilmemişse 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.

   Not: Değişiklikleri etkinleştirmek ve devre dışı bırakmak için uygulamanızın hata ayıklama yapılabilir bir derleme varyantını kullanmanız gerekir.

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

• Uygulamanın targetSdkVersion'sinden 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 etkindir ve kullanıcı arayüzündeki Varsayılan Olarak 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 kısıtlanmış 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 etkinleştirilir. Örneğin, Android 13'te (API düzeyi 33) targetSDKVersion tarafından engellenen bir davranış değişikliği, kullanıcı arayüzünde targetSdkVersion >=33 için etkin başlıklı bir bölümde listelenir. Android'in bazı eski sürümlerinde bu bölümün başlığı "API_LEVEL numaralı SDK'dan sonra etkinleştirildi" şeklindedir.

  Not: API düzeyi kesinleşinceye kadar Android 15 önizlemesi sırasında, yalnızca Android 15 hedeflendiğinde etkinleştirilen bazı değişikliklerde, API düzeyi için nihai ve varsayılan API düzeyi 35 yerine 10000 değeri kullanılır.

1. resimde Varsayılan olarak 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, ilgili Android sürümünün uyumluluk çerçevesi listesinde değişiklik açıklamasını okuyun.

logcat'i kullanarak etkinleştirilen değişiklikleri belirleme

Her davranış değişikliği için, uygulamanız etkilenen API'yi ilk kez çağrdığında sistem aşağıdaki gibi bir logcat mesajı döndürür:

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

Not: Her değişiklik, işlem başına en fazla bir kez günlüğe kaydedilir. Alakalı tüm Logcat mesajlarını gördüğünüzden emin olmak için uygulamanızın sürecini zorla durdurup yeniden başlatın.

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

Değişiklik kimliği

Uygulamayı etkileyen değişikliği belirtir. Bu değer, Uygulama Uyumluluğu Değişiklikleri ekranında listelenen davranış değişikliklerinden biriyle eşlenir (bkz. Şekil 1). Bu örnekte 194833441, NOTIFICATION_PERM_CHANGE_ID ile eşlenir.

UID

Değişiklikten hangi uygulamanın etkilendiğini gösterir.

Eyalet

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

Durum aşağıdaki 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ılır ve uygulamayı etkilemez. Not: Bu değişiklik, uygulamanın targetSDKVersion değeri gerekli eşiğin altında olduğu için devre dışı bırakılırsa uygulama, targetSDKVersion değerini daha yüksek bir sürümü hedefleyecek şekilde artırdığında varsayılan olarak etkinleştirilir.
LOGGED	Değişiklik, uyumluluk çerçevesi üzerinden günlüğe kaydedilir ancak etkinleştirilemez veya devre dışı bırakılamaz. Bu değişiklik etkinleştirilemez olsa da uygulamanızın davranışını etkileyebilir. Daha fazla bilgi için söz konusu Android sürümünün uyumluluk çerçevesi listesinde değişikliğin açıklamasını inceleyin. Bu tür değişiklikler genellikle deneyseldir ve yoksayılabilir.

ADB'yi kullanarak etkin değişiklikleri belirleme

Cihazın tamamındaki tüm değişiklikleri (hem etkinleştirilenler hem de devre dışı bırakılanlar) görmek için aşağıdaki ADB komutunu çalıştırın:

adb shell dumpsys platform_compat

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

Değişiklik kimliği

Bu davranış değişikliği için benzersiz bir tanımlayıcı. Ö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 kontrol edildiği (varsa).

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

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, varsayılan olarak etkinleştirilen bir değişiklik varsa geliştirici seçeneklerini veya ADB'yi kullanarak değişikliği devre dışı bıraktıysanız uygulamanızın paket adı listelenir. Bu durumda, çıkış şu şekilde olur:

packageOverrides={com.my.package=false}

targetSDKVersion tarafından engellenen değişiklikler varsayılan olarak etkinleştirilebilir veya devre dışı bırakılabilir. Bu nedenle, paket listesi bu uygulamaların targetSDKVersion'lerine bağlı olarak hem true hem de false örnekleri 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 dokümanlarına dahil edilmiştir. 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:

• Android 15 (API düzeyi 35)
• Android 14 (API düzeyi 34)
• Android 13 (API düzeyi 33)
• Android 12 (API düzeyleri 31 ve 32)
• Android 11 (API düzeyi 30)

Değişiklikleri ne zaman değiştirmelisiniz?

Uyumluluk çerçevesinin ana amacı, uygulamanızı Android'in yeni sürümleriyle test ederken size kontrol ve esneklik sunmaktır. Bu bölümde, uygulamanızı test edip hata ayıklamaya çalışırken değişiklikleri ne zaman etkinleştireceğinizi veya devre dışı bırakacağınızı belirlemek için kullanabileceğiniz bazı stratejiler açıklanmaktadır.

Değişiklikleri devre dışı bırakma

Değişikliklerin ne zaman devre dışı bırakılacağına karar vermek genellikle değişikliğin targetSDKVersion tarafından kısıtlanıp kısıtlanmadığına 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'den bağımsız olarak belirli bir platform sürümü için varsayılan olarak etkinleştirilir. Böylece, uygulamanızı bu platform sürümünde çalıştırarak uygulamanızın etkilenip etkilenmediğini görebilirsiniz.

Örneğin, Android 15'i (API düzeyi 35) hedeflemeye hazırlanıyorsanız uygulamanızı Android 15 çalıştıran bir cihaza yükleyerek başlayabilir ve uygulamanızı normal test iş akışlarınızı kullanarak test edebilirsiniz. Uygulamanız sorunla karşılaşırsa diğer sorunları test etmeye devam etmek için soruna neden olan değişikliği devre dışı bırakabilirsiniz.

Bu değişiklikler targetSDKVersion'ten bağımsız olarak tüm uygulamaları etkileyebileceğinden, genellikle targetSDKVersion tarafından engellenen değişikliklerden önce uygulamanızı bu değişiklikler için test edip güncellemeniz gerekir. Bu sayede, kullanıcılarınızın cihazlarını yeni bir platform sürümüne güncellediklerinde uygulama deneyiminde düşüş yaşanmaz.

Android'in herkese açık sürümünü kullanırken bu değişiklikleri devre dışı bırakamadığınız için bu değişiklikleri test etmeye de öncelik vermelisiniz. İdeal olarak, bu değişiklikleri Android'in her sürümü için sürüm önizleme aşamasındayken test etmeniz gerekir.

targetSDKVersion tarafından kontrol edilen değişiklikler

Uygulamanız belirli bir targetSDKVersion sürümünü hedefliyorsa bu sürüm tarafından engellenen tüm değişiklikler varsayılan olarak etkinleştirilir. Bu nedenle, uygulamanızın targetSDKVersion sürümünü 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 etkilenebileceğinden, uygulamanızı test edip hata ayıklamaya çalışırken bu değişikliklerden bazılarını tek tek devre dışı bırakmanız gerekebilir.

Değişiklikleri ne zaman etkinleştirmelisiniz?

Belirli bir targetSDKVersion tarafından engellenen değişiklikler, bir uygulama engellenen sürümden daha düşük bir SDK sürümünü hedeflediğinde varsayılan olarak devre dışı bırakılır. Genellikle yeni bir targetSdkVersion'yi hedeflemeye hazırlanırken uygulamanızı test edip hata ayıklamak için uygulamanızda yapmanız gereken davranış değişiklikleri listesi olur.

Örneğin, uygulamanızı önümüzdeki targetSdkVersion'te yapılacak bir dizi platform değişikliğine karşı test ediyorsunuzdur. Geliştirici seçeneklerini veya ADB komutlarını kullanarak uygulama manifestinizi değiştirip her değişikliği tek seferde etkinleştirmek yerine, her bir sınırlı değişikliği tek tek etkinleştirip test edebilirsiniz. Bu ek denetim, değişiklikleri tek tek test etmenize ve uygulamanızın birden fazla bölümünü aynı anda hata ayıklamadan ve güncellemekten kaçınmanıza yardımcı olabilir.

Bir değişikliği etkinleştirdikten sonra, normal test iş akışlarınızı kullanarak uygulamanızı test edebilir ve hata ayıklayabilirsiniz. Sorunla karşılaşırsanız sorunun nedenini belirlemek için günlüklerinizi kontrol edin. Sorunun etkinleştirilen bir platform değişikliğinden kaynaklanıp kaynaklanmadığı net değilse bu değişikliği devre dışı bırakıp uygulamanızın ilgili bölümünü yeniden test etmeyi deneyin.

Değişiklikleri etkinleştirme veya devre dışı bırakma

Uyumluluk çerçevesi, geliştirici seçeneklerini veya ADB komutlarını kullanarak her değişikliği etkinleştirmenize ya da devre dışı bırakmanıza olanak tanır. Değişiklikleri etkinleştirmek veya devre dışı bırakmak uygulamanızın kilitlenmesine ya da önemli güvenlik değişikliklerinin devre dışı bırakılmasına neden olabileceğinden, değişiklikleri ne zaman etkinleştirebileceğinizle ilgili bazı kısıtlamalar vardır.

Not: Geliştirici seçeneklerini veya ADB komutlarını kullanarak bir uygulamada değişiklik yaptığınızda, geçersiz kılma işleminizin hemen geçerli olması için uygulama kapatılır.

Geliştirici seçeneklerini kullanarak değişiklikleri etkinleştirme/devre dışı bırakma

Değişiklikleri etkinleştirmek veya devre dışı bırakmak için geliştirici seçeneklerini kullanın. Geliştirici seçeneklerini bulmak üzere aşağıdaki adımları uygulayın:

1. Geliştirici seçenekleri etkinleştirilmemişse 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şiklik listesinde, etkinleştirmek veya devre dışı bırakmak istediğiniz değişikliği bulun ve anahtara dokunun.

   

ADB'yi kullanarak değişiklikleri etkinleştirme/devre dışı bırakma

ADB'yi kullanarak bir değişikliği etkinleştirmek veya devre dışı bırakmak 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 (ör. 194833441) veya CHANGE_NAME (ör. NOTIFICATION_PERM_CHANGE_ID) ile uygulamanızın PACKAGE_NAME değerini iletin.

Bir değişikliği varsayılan durumuna sıfırlamak için aşağıdaki komutu da kullanabilirsiniz. Bu komut, ADB veya geliştirici seçeneklerini kullanarak ayarladığınız tüm geçersiz kılma işlemlerini kaldırır:

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Değişiklikleri açma/kapatma ile ilgili kısıtlamalar

Varsayılan olarak her davranış değişikliği etkin veya devre dışıdır. Tüm uygulamaları etkileyen değişiklikler varsayılan olarak etkindir. Diğer değişiklikler targetSdkVersion ile kontrol edilir. Bu değişiklikler, bir uygulama ilgili SDK sürümünü veya daha yeni bir sürümü hedeflediğinde varsayılan olarak etkinleştirilir ve bir uygulama, sınırlı sürümden daha eski bir SDK sürümünü hedeflediğinde varsayılan olarak devre dışı bırakılır. Bir değişikliği etkinleştirdiğinizde veya devre dışı bıraktığınızda, varsayılan durumunu geçersiz kılarsınız.

Uyumluluk çerçevesinin kötüye kullanılmasını önlemek için değişiklikleri ne zaman değiştirebileceğiniz konusunda bazı kısıtlamalar vardır. Bir değişikliği etkinleştirip etkinleştiremeyeceğiniz, değişikliğin türüne, uygulamanızın hata ayıklama özelliğine sahip olup olmadığına ve cihazınızda çalışan derleme türüne bağlıdır. Aşağıdaki tabloda, farklı değişiklik türlerini ne zaman etkinleştirebileceğiniz açıklanmaktadır:

Derleme türü	Hata ayıklanamayacak uygulama	Hata ayıklanabilir uygulama
	Tüm değişiklikler	targetSDKVersion tarafından kontrol edilen değişiklikler	Diğer tüm değişiklikler
Geliştirici Önizlemesi veya Beta sürümü	Açma/kapatma yapılamıyor	Aç/kapatabilir	Aç/kapatabilir
Herkese açık kullanıcı derlemesi	Açma/kapatma yapılamıyor	Aç/kapatabilir	Açma/kapatma yapılamıyor