Uyumluluk çerçevesi araçları

Android 11, uygulamanızı Android platformunun yeni sürümlerindeki davranış değişikliklerine karşı test etme ve hatalarını ayıklama için yeni geliştirici araçları sunar. Bu araçlar, uygulama geliştiricilerin geliştirici seçeneklerini veya ADB'yi kullanarak uyumluluğu bozacak 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 yeni 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 esneklikten yararlanın.

Uyumluluk çerçevesi araçlarını kullandığınızda Android platformu, temel testleri gerçekleştirmek için targetSDKVersion dosyanızı değiştirmenize veya uygulamanızı yeniden derlemenize gerek kalmadan dahili mantığını otomatik olarak uyarlar. Değişiklikler tek tek etkinleştirilip devre dışı bırakılabildiğinden, her seferinde bir davranış değişikliğini izole edebilir, test edebilir ve hatalarını ayıklayabilir ya da ö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şme şekli değişebilir. 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

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

Hangi değişikliklerin etkinleştirildiğini görebilir ve bir 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 etkin değilse 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 girer:

• Uygulamanın targetSdkVersion'sından bağımsız olarak, Android'in söz konusu 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 Etkinleştirilen 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 sınırlanan 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 ile sınırlandırılmış bir davranış değişikliği, kullanıcı arayüzünde targetSdkVersion >=33 için etkinleştirildi başlıklı bir bölümde listelenir. Android'in bazı eski sürümlerinde bu bölümün başlığı "Enabled After SDK API_LEVEL" (API_LEVEL numaralı SDK'dan sonra etkinleştirildi) olarak gösterilir.

Ayrıca, Şekil 1'de Varsayılan Olarak Devre Dışı Bırakılan Değişiklikler adlı bir bölüm olduğunu da fark edeceksiniz. 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 listesindeki 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ın etkilenen API'yi çağırdığı ilk seferde sistem, aşağıdaki gibi bir logcat mesajı verir:

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

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

Değişiklik kimliği

Uygulamayı hangi değişikliğin etkilediğini gösterir. Bu değer, Uygulama Uyumluluğu Değişiklikleri ekranında listelenen davranış değişikliklerinden biriyle eşleşir (bkz. Şekil 1). Bu örnekte, 194833441, NOTIFICATION_PERM_CHANGE_ID ile eşlenir.

UID

Değişiklikten etkilenen uygulamayı gösterir.

Eyalet

Değişikliğin uygulamayı etkileyip etkilemediğini gösterir.

Durum ş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ı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, 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 aracılığıyla kaydedilir ancak açılıp kapatılamaz. Bu değişiklik açılıp kapatılamasa da uygulamanızın davranışını etkileyebilir. Daha fazla bilgi için Android sürümüne yönelik uyumluluk çerçevesi listesindeki değişikliğin açıklamasını inceleyin. Çoğu durumda bu tür değişiklikler deneyseldir ve yoksayılabilir.

ADB'yi kullanarak etkinleştirilen değişiklikleri belirleme

Tüm cihazdaki değişikliklerin tamamını (hem etkinleştirilen hem de devre dışı bırakılan) görmek için aşağıdaki ADB komutunu çalıştırın:

adb shell dumpsys platform_compat

Çıkışta her değişiklik için aşağıdaki bilgiler listelenir:

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 ile sınırlı olduğu (varsa).

Örneğin, bu değişiklik yalnızca SDK sürümü 33 veya daha yüksek olan uygulamalar için etkinleştirilmişse enableAfterTargetSdk=32 çıkışı yapılır. Değişiklik targetSDKVersion tarafından kontrol edilmiyorsa enableAfterTargetSdk=0 çıkışı yapılır.

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

packageOverrides={com.my.package=false}

targetSDKVersion ile sınırlanan değişiklikler varsayılan olarak etkinleştirilebilir veya devre dışı bırakılabilir. Bu nedenle, paket listesi, söz konusu uygulamaların her birinin targetSDKVersion değerine bağlı olarak hem true hem de 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 dokümanında yer alı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:

• Android 16 (API düzeyi 36)
• 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 etkinleştirip devre dışı bırakmalısınız?

Uyumluluk çerçevesinin temel amacı, uygulamanızı Android'in yeni sürümleriyle test ederken kontrol ve esneklik sağlamaktır. Bu bölümde, uygulamanızı test edip hatalarını ayıklarken 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 ne zaman devre dışı bırakmalısınız?

Değişiklikleri ne zaman devre dışı bırakacağınıza karar verirken genellikle değişikliğin targetSDKVersion tarafından kontrol edilip edilmediği dikkate alınır.

Tüm uygulamalar için etkinleştirilen değişiklikler

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ünde varsayılan olarak etkinleştirilir. Bu nedenle, uygulamanızı söz konusu platform sürümünde çalıştırarak uygulamanızın etkilenip etkilenmediğini görebilirsiniz.

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

Bu değişiklikler targetSDKVersion'dan bağımsız olarak tüm uygulamaları etkileyebileceğinden, targetSDKVersion ile sınırlanan değişikliklerden önce uygulamanızı bu değişikliklere göre test etmeniz ve güncellemeniz gerekir. Bu sayede, kullanıcılarınız cihazlarını yeni bir platform sürümüne güncellediklerinde uygulama deneyimlerinin kötüleşmemesi sağlanır.

Android'in herkese açık sürümünü kullanırken bu değişiklikleri devre dışı bırakamayacağınız için bu değişikliklerin test edilmesine de öncelik vermelisiniz. İdeal olarak, bu değişikliklerle ilgili testleri Android'in her sürümü için söz konusu sürüm önizleme aşamasındayken yapmanız gerekir.

targetSDKVersion tarafından kontrol edilen değişiklikler

Uygulamanız belirli bir targetSDKVersion sürümünü hedefliyorsa bu sürümle sınırlanan 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çirirken uygulamanız aynı anda birçok yeni değişiklikten etkilenmeye başlar.

Uygulamanız bu değişikliklerden birden fazla etkileniyor olabilir. Bu nedenle, uygulamanızı test edip hatalarını ayıklarken bu değişikliklerden bazılarını tek tek devre dışı bırakmanız gerekebilir.

Değişiklikleri ne zaman etkinleştirebilirsiniz?

Belirli bir targetSDKVersion ile sınırlanan değişiklikler, bir uygulama sınırlanan 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 hedeflemeye hazırlanırken uygulamanızı test etmeniz ve hatalarını ayıklamanız gereken davranış değişikliklerinin bir listesi olur.

Örneğin, uygulamanızı önümüzdeki targetSdkVersion içinde bir dizi platform değişikliğine karşı test ediyor olabilirsiniz. Geliştirici seçeneklerini veya ADB komutlarını kullanarak, uygulama manifestinizi değiştirmek ve her değişikliği aynı anda etkinleştirmek yerine, her bir sınırlı değişikliği tek tek etkinleştirip test edebilirsiniz. Bu ek kontrol, değişiklikleri ayrı ayrı test etmenize ve uygulamanızın birden fazla bölümünde aynı anda hata ayıklayıp güncelleme yapmaktan kaçınmanıza yardımcı olabilir.

Bir değişikliği etkinleştirdikten sonra, her zamanki test iş akışlarınızı kullanarak uygulamanızı test edip hatalarını ayıklayabilirsiniz. Sorunlarla karşılaşırsanız sorunun nedenini belirlemek için günlüklerinizi kontrol edin. Sorunun etkinleştirilmiş bir platform değişikliğinden kaynaklanıp kaynaklanmadığı net değilse bu değişikliği devre dışı bırakmayı ve ardından uygulamanızın ilgili alanı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 açıp kapatmanıza olanak tanır. Değişikliklerin etkinleştirilmesi veya devre dışı bırakılması, uygulamanızın kilitlenmesine ya da önemli güvenlik değişikliklerinin devre dışı bırakılmasına neden olabileceğinden değişiklikleri etkinleştirebileceğiniz veya devre dışı bırakabileceğiniz zamanlarla ilgili bazı kısıtlamalar vardır.

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

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

1. Geliştirici seçenekleri etkin değilse etkinleştirin.
2. Cihazınızın Ayarlar uygulamasını açın ve 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, açmak veya kapatmak istediğiniz değişikliği bulup düğmeye dokunun.

   

ADB kullanarak değişiklikleri açma/kapatma

ADB 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) ve uygulamanızın PACKAGE_NAME öğesini 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ılmaları kaldırır:

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Değişiklikleri etkinleştirme/devre dışı bırakma 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 etkindir. Diğer değişiklikler targetSdkVersion ile sınırlıdır. 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. Bir uygulama, sınırlı sürümden daha eski bir SDK sürümünü hedeflediğinde ise 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ü amaçlı kullanılmasını önlemek için değişiklikleri ne zaman etkinleştirebileceğinizle ilgili bazı kısıtlamalar vardır. Bir değişikliği açıp kapatabilmeniz; değişikliğin türüne, uygulamanızın hata ayıklanabilir olup olmadığına ve cihazınızda çalışan derlemenin 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: