Uyumluluk çerçevesi araçları

Android 11, uygulamanızı Android platformunun daha yeni sürümlerindeki davranış değişikliklerine karşı test etmek ve hata ayıklamak için yeni geliştirici araçları sunar. Bu araçlar, uygulama geliştiricilerin geliştirici seçeneklerini veya ADB'yi kullanarak zarar veren değişiklikleri tek tek açıp kapatması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 esneklikten yararlanın.

Uyumluluk çerçevesi araçlarını kullandığınızda Android platformu, dahili mantığını otomatik olarak uyarlar. Bu sayede, temel testleri gerçekleştirmek için targetSDKVersion değerinizi değiştirmeniz veya uygulamanızı yeniden derlemeniz gerekmez. Değişiklikler ayrı ayrı açılıp kapatı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

Davranış değişikliği etkinleştirildiğinde, uygulamanızın bu değişiklikten etkilenen platform API'lerine erişim ş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. Uygulama Uyumluluğu Değişiklikleri ekranında geliştirici seçeneklerinde görebilirsiniz.

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 etkinleştirilmemişse etkinleştirin.
2. Cihazınızın Ayarlar uygulamasını açıp Sistem > Gelişmiş > Geliştirici seçenekleri > Uygulama Uyumluluğuyla İlgili Değişiklikler'e gidin.

3. Listeden uygulamanızı seçin.

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

• Uygulamanın targetSdkVersion değerinden 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 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 geçitli 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ığı "API_LEVEL numaralı SDK'dan sonra etkinleştirildi" olarak gösterilir.

Ayrıca, Şekil 1'de Varsayılan Olarak Devre Dışı 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 listesindeki değişiklik açıklamasını okuyun.

Logcat kullanarak etkinleştirilen 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 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ğuyla İlgili Değişiklikler 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.

Durum

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

Durum, şu değerlerden biri olabilir:

Durum	Anlamı
ENABLED	Değişiklik etkinleştirilir ve 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: 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 aracılığıyla kaydedilir ancak etkinleştirilip devre dışı bırakılamaz. Bu değişiklik etkinleştirilip devre dışı bırakı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 kullanarak etkinleştirilen değişiklikleri belirleme

Cihazın tamamındaki tüm değişiklikleri (hem etkin hem de devre dışı) 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ğ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 ile sınırlandırıldığı (varsa).

Örneğin, bu değişiklik yalnızca SDK sürümü 33 veya sonraki sürümleri hedefleyen uygulamalar için etkinleştirilmişse enableAfterTargetSdk=32 çıkışı yapılır. Değişiklik targetSDKVersion tarafından engellenmiyorsa 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 tarafından kısıtlanan değişiklikler varsayılan olarak etkinleştirilebilir veya devre dışı bırakılabilir. Bu nedenle paket listesi, her bir uygulamanın 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ü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 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üzeyi 31 ve 32)
• Android 11 (API düzeyi 30)

Değişiklikleri açma/kapatma zamanı

Uyumluluk çerçevesinin temel amacı, uygulamanızı Android'in daha yeni sürümleriyle test ederken size kontrol ve esneklik sağlamaktır. Bu bölümde, uygulamanızı test ederken ve uygulamanızda hata 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 devre dışı bırakma zamanı

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 değerinden bağımsız olarak belirli bir platform sürümü için varsayılan olarak etkinleştirilir. Böylece, uygulamanızı söz konusu platform sürümünde çalıştırarak etkilenip etkilenmediğini görebilirsiniz.

Örneğin, Android 16'yı (API düzeyi 36) hedeflemeye hazırlanıyorsanız uygulamanızı Android 16 çalıştıran bir cihaza yükleyebilir ve normal 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ırakıp diğer sorunları test etmeye devam edebilirsiniz.

Bu değişiklikler, targetSDKVersion değerinden bağımsız olarak tüm uygulamaları etkileyebilir. Bu nedenle, targetSDKVersion ile sınırlı değişikliklerden önce uygulamanızı bu değişiklikler için test edip güncelleyin. Bu sayede, kullanıcılar yeni bir platform sürümüne geçtiklerinde deneyimlerinin kötüleşmemesi sağlanır.

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

targetSDKVersion tarafından kısıtlanan değişiklikler

Uygulamanız belirli bir targetSDKVersion sürümünü hedefliyorsa bu sürüm tarafından kısıtlanan 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şikliklerin birden fazlasından etkilenebileceğinden, uygulamanızı test edip hata ayıklarken bu değişikliklerden bazılarını tek tek devre dışı bırakmanız gerekebilir.

Değişiklikleri etkinleştirme zamanı

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 sürümünü hedeflemeye hazırlanırken uygulamanızı test etmeniz ve hata ayıklamanız gereken davranış değişikliklerinin bir listesi olur.

Örneğin, uygulamanızı bir sonraki 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 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, normal test iş akışlarınızı kullanarak uygulamanızı test edebilir ve 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ı deneyin ve ardından uygulamanızın bu alanını yeniden test edin.

Değişiklikleri açma veya kapatma

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şiklikleri etkinleştirmek veya devre dışı bırakmak uygulamanızın kilitlenmesine ya da önemli güvenlik değişikliklerinin devre dışı kalmasına neden olabileceğinden değişiklikleri ne zaman etkinleştirebileceğinizle ilgili bazı kısıtlamalar vardı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 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çın ve Sistem > Gelişmiş > Geliştirici seçenekleri > Uygulama Uyumluluğuyla İlgili Değişiklikler'e 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 bulup anahtara dokunun.

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

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 değerini iletin.

Bir değişikliği varsayılan durumuna sıfırlamak ve ADB veya geliştirici seçeneklerini kullanarak ayarladığınız geçersiz kılma işlemlerini 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 etkindir. Diğer değişiklikler targetSdkVersion tarafından engellenir. Bu değişiklikler, bir uygulama ilgili SDK sürümünü veya daha yüksek bir sürümü hedeflediğinde varsayılan olarak etkinleştirilir ve geçitli sürümden daha düşük bir SDK sürümünü hedeflediğinde varsayılan olarak devre dışı bırakılır. Bir değişikliği açıp kapattığınızda varsayılan durumunu geçersiz kılmış olursunuz.

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 etkinleştirip devre dışı bırakabilmeniz; 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: