Google Play, platform sürümü gereksinimlerini karşılamayan cihazlardan uygulamanızı filtrelemek için uygulama manifestinizde beyan edilen <uses-sdk> özelliklerini kullanır. Bu özellikleri ayarlamadan önce Google Play filtrelerini anladığınızdan emin olun.
- söz dizimi:
<uses-sdk android:minSdkVersion="integer" android:targetSdkVersion="integer" android:maxSdkVersion="integer" />
- içerdiği:
<manifest>- description:
Bir uygulamanın Android platformunun bir veya daha fazla sürümüyle uyumluluğunu API düzeyi tam sayısı ile ifade edebilmenizi sağlar. Bir uygulama tarafından ifade edilen API düzeyi, belirli bir Android sisteminin API düzeyiyle karşılaştırılır. Bu düzey, farklı Android cihazlara göre değişebilir.
Bu öğe, adının aksine yazılım geliştirme kitinin (SDK) veya Android platformunun sürüm numarasını değil, API seviyesini belirtmek için kullanılır. API düzeyi her zaman tek bir tam sayıdır. İlişkili Android sürümü numarasından API düzeyini elde edemezsiniz. Örneğin, ana sürümle ya da ana ve alt sürümlerin toplamıyla aynı değildir.
Uygulamalarınız için sürüm oluşturma hakkındaki belgeyi de okuyun.
- özellikler:
-
android:minSdkVersion- Uygulamanın çalışması için gereken minimum API seviyesini belirten bir tam sayı. Android sistemi, API düzeyi bu özellikte belirtilen değerden düşükse kullanıcının uygulamayı yüklemesini engeller. Bu özelliği her zaman bildir.
Dikkat: Bu özelliği bildirmezseniz sistem, varsayılan değerin "1" olduğunu varsayar. Bu değer, uygulamanızın tüm Android sürümleriyle uyumlu olduğunu ifade eder. Yoksa ve uygun
minSdkVersiondeğerini tanımlamadıysanız, API düzeyi uyumsuz olan bir sisteme yüklendiğinde uygulama, kullanılamayan API'lere erişmeye çalışırken çalışma zamanında kilitlenir. Bu nedenle,minSdkVersionözelliğinde uygun API seviyesini bildirdiğinizden emin olun. android:targetSdkVersion- Uygulamanın hedeflediği API seviyesini belirten bir tam sayı. Ayarlanmazsa varsayılan değer,
minSdkVersioniçin verilen değere eşit olur.Bu özellik, sisteme hedef sürüm karşısında test yaptığınızı bildirir ve sistem, uygulamanızın hedef sürümle uyumlu olmasını sağlamak için hiçbir uyumluluk davranışını etkinleştirmez. Uygulama eski sürümlerde (
minSdkVersionsürümüne kadar) çalışmaya devam edebilir.Android her yeni sürümde geliştiğinden bazı davranışlar, hatta görünümler bile değişebilir. Bununla birlikte, platformun API düzeyi uygulamanızın
targetSdkVersiontarafından beyan edilen sürümden yüksekse sistem, uygulamanızın beklediğiniz şekilde çalışmaya devam etmesi için uyumluluk davranışlarını etkinleştirebilir.targetSdkVersionAPI'sini, çalıştırıldığı platformun API düzeyiyle eşleşecek şekilde belirterek bu tür uyumluluk davranışlarını devre dışı bırakabilirsiniz.Örneğin, bu değeri "11" veya daha yüksek bir değere ayarlamak, sistemin Android 3.0 veya sonraki sürümler üzerinde çalışırken uygulamanıza Holo varsayılan temasını uygulamasına izin verir ve API düzeyi 11 desteği dolaylı olarak büyük ekranları desteklediğinden büyük ekranlarda çalışırken ekran uyumluluğu modunu devre dışı bırakır.
Bu özellik için ayarladığınız değere bağlı olarak sistemin etkinleştirebileceği birçok uyumluluk davranışı vardır. Bu davranışların birkaçı,
Build.VERSION_CODESreferansında karşılık gelen platform sürümleri tarafından açıklanmıştır.Uygulamanızı her Android sürümüyle birlikte korumak için bu özelliğin değerini en son API düzeyiyle eşleşecek şekilde artırın, ardından uygulamanızı ilgili platform sürümünde kapsamlı bir şekilde test edin.
Kullanıma sunuldu: API düzeyi 4
- Uygulamanın çalışacağı maksimum API seviyesini belirten bir tam sayı.
Android 1.5, 1.6, 2.0 ve 2.0.1'de sistem, bir uygulamayı yüklerken ve sistem güncellemesinden sonra uygulamayı yeniden doğrularken bu özelliğin değerini kontrol eder. Her iki durumda da uygulamanın
maxSdkVersionözelliği, sistemin kendisi tarafından kullanılan API düzeyinden düşükse sistem uygulamanın yüklenmesine izin vermez. Sistem güncellemesinden sonra yeniden doğrulama yapılması durumunda uygulamanız cihazdan etkili bir şekilde kaldırılır.Sistem güncellemelerinden sonra bu özelliğin uygulamanızı nasıl etkileyebileceğini göstermek için aşağıdaki örneği inceleyin:
Manifest dosyasında
maxSdkVersion="5"belirten bir uygulama Google Play'de yayınlanır. Cihazı Android 1.6 (API düzeyi 4) çalıştıran bir kullanıcı, uygulamayı indirip yükler. Kullanıcı birkaç hafta sonra sistemi Android 2.0 (API düzeyi 5) için kablosuz olarak günceller. Güncelleme yüklendikten sonra sistem, uygulamanınmaxSdkVersiondeğerini kontrol eder ve uygulamayı başarıyla yeniden doğrular.Uygulama normal şekilde çalışır. Ancak bir süre sonra cihaz, bu kez Android 2.0.1 (API düzeyi 6) sürümüne olmak üzere başka bir sistem güncellemesi alır. Sistemin kendi API düzeyi (6), artık uygulama tarafından desteklenen maksimum değerden (5) daha yüksek olduğundan, güncelleme sonrasında sistem uygulamayı yeniden doğrulayamaz. Sistem, aslında uygulamayı cihazdan kaldırarak kullanıcının görmesini engeller.
Uyarı: Bu özelliğin belirtilmesi önerilmez. Öncelikle, bu özelliği, kullanıma sunulduklarında Android platformunun yeni sürümlerine uygulamanın dağıtımını engellemek için bir araç olarak ayarlamanıza gerek yoktur. Platformun yeni sürümleri, tasarımı gereği geriye dönük olarak tamamen uyumludur. Uygulamanız yalnızca standart API'leri kullandığı ve geliştirme en iyi uygulamalarını takip ettiği sürece yeni sürümlerde düzgün çalışır. İkinci olarak, bazı durumlarda bu özelliğin bildirilmesi, sistem daha yüksek bir API seviyesine güncellendikten sonra uygulamanızın kullanıcıların cihazlarından kaldırılmasına neden olabilir. Uygulamanızın yüklenme olasılığı yüksek olan çoğu cihaz, düzenli aralıklarla kablosuz olarak sistem güncellemelerini alır. Bu nedenle, bu özelliği ayarlamadan önce bu güncellemelerin uygulamanız üzerindeki etkisini göz önünde bulundurun.
Kullanıma sunuldu: API düzeyi 4
Android'in bazı sürümleri (Android 2.0.1'den sonraki), yükleme veya yeniden doğrulama sırasındamaxSdkVersionözelliğini kontrol etmez ya da zorunlu kılmaz. Ancak Google Play, kullanıcılara indirilebilecek uygulamalar sunarken bu özelliği filtre olarak kullanmaya devam eder.
- tanıtıldığı yer:
- API düzeyi 1
API düzeyi nedir?
API düzeyi, Android platformunun bir sürümü tarafından sunulan çerçeve API düzeltmesini benzersiz şekilde tanımlayan bir tam sayı değeridir.
Android platformu, uygulamaların temel Android sistemiyle etkileşim kurmak için kullanabileceği bir çerçeve API'si sağlar. Çerçeve API'si şunları içerir:
- Temel paket ve sınıf kümesi
- Manifest dosyası tanımlamak için kullanılan XML öğeleri ve özellikleri grubu
- Kaynakları tanımlamak ve kaynaklara erişmek için kullanılan bir dizi XML öğesi ve özelliği
- Amaçlar grubu
- Uygulamaların isteyebileceği bir izin grubu ve sistemdeki izin yaptırımları
Android platformunun takip eden her sürümü, sunduğu Android uygulama çerçevesi API'si için güncellemeler içerebilir.
Framework API'de yapılan güncellemeler, yeni API'nin önceki API sürümleriyle uyumlu kalmasını sağlayacak şekilde tasarlanmıştır. Diğer bir deyişle, API'deki çoğu değişiklik eklemelidir ve yeni ya da yeni işlevler getirir. API'nin bazı bölümleri yeni sürüme geçirildiğinde, değiştirilen eski parçalar kullanımdan kaldırılır ancak kaldırılmaz. Böylece mevcut uygulamalar bunları kullanmaya devam edebilir.
Çok nadir durumlarda, API'nin bazı parçaları değiştirilir veya kaldırılır. Ancak genellikle bu tür değişiklikler, yalnızca API dayanıklılığını ve uygulama veya sistem güvenliğini desteklemek için gerekli olur. Önceki düzeltmelere ait diğer tüm API parçaları, herhangi bir değişiklik yapılmadan aktarılır.
Bir Android platformunun yayınladığı çerçeve API'si, API düzeyi adı verilen bir tam sayı tanımlayıcı kullanılarak belirtilir. Her Android platform sürümü tam olarak bir API düzeyini destekler ancak önceki tüm API düzeyleri (API düzeyi 1'e kadar) için destek örtülüdür. Android platformunun ilk sürümü API düzeyi 1'i sağlamıştır ve sonraki sürümler API düzeyini artırmıştır.
Aşağıdaki tabloda, Android platformunun her sürümü tarafından desteklenen API düzeyi belirtilmektedir. Her sürümü çalıştıran cihazların göreli sayısı hakkında bilgi için Dağıtım kontrol paneli'ne bakın.
Android'de API düzeyi kullanımları
API düzeyi tanımlayıcısı, kullanıcılar ve uygulama geliştiriciler için mümkün olan en iyi deneyimi sağlamada önemli bir rol oynar:
- Android platformunun, desteklediği maksimum çerçeve API düzeltmesini tanımlamasını sağlar.
- Uygulamaların, ihtiyaç duydukları çerçeve API revizyonunu açıklamasını sağlar.
- Sistemin, kullanıcının cihazına uygulama yükleme işlemi için gerekli işlemleri yapmasına olanak tanır. Böylece, sürümle uyumsuz uygulamalar yüklenmez.
Her Android platform sürümü, API düzeyi tanımlayıcısını Android sisteminin kendi içinde dahili olarak depolar.
Uygulamalar, çerçeve API'si (<uses-sdk>) tarafından sağlanan manifest öğesini kullanarak çalışabilecekleri minimum ve maksimum API düzeylerinin yanı sıra, desteklenecek şekilde tasarlandıkları tercih edilen API düzeyini tanımlayabilir. Bu öğe üç temel özellik sunar:
android:minSdkVersion: Uygulamanın çalışabileceği minimum API düzeyi. Varsayılan değer "1"dir.android:targetSdkVersion: Uygulamanın çalışmak üzere tasarlandığı API düzeyi. Bazı durumlarda bu, uygulamanın yalnızca minimum API düzeyi için tanımlananlarla sınırlandırılması yerine, hedef API düzeyinde tanımlanan manifest öğelerini veya davranışları kullanmasına olanak tanır.android:maxSdkVersion: Uygulamanın çalışabileceği maksimum API düzeyi. Önemli: Özelliği kullanmadan önce bu sayfadaki bu özellikle ilgili bilgileri okuyun.
Örneğin, bir uygulamanın çalışması için gereken minimum sistem API'si düzeyini belirtmek amacıyla uygulama, manifest dosyasına android:minSdkVersion özelliğine sahip bir <uses-sdk> öğesi ekler. android:minSdkVersion değeri, uygulamanın çalışabileceği Android platformunun en eski sürümünün API düzeyine karşılık gelen tam sayıdır.
Kullanıcı bir uygulamayı yüklemeye çalıştığında veya sistem güncellemesinden sonra bir uygulamayı yeniden doğruladığında, Android sistemi önce uygulamanın manifest dosyasındaki <uses-sdk> özelliklerini kontrol eder ve değerleri kendi dahili API düzeyiyle karşılaştırır. Sistem, yalnızca aşağıdaki koşullar karşılandığında yüklemenin başlatılmasına izin verir:
- Bir
android:minSdkVersionözelliği tanımlanırsa özelliğin değeri sistemin API düzeyi tam sayısından küçük veya ona eşit olur. Belirtilmezse sistem, uygulamanın API düzeyi 1'i gerektirdiğini varsayar. - Bir
android:maxSdkVersionözelliği tanımlanırsa özelliğin değeri sistemin API düzeyi tam sayısına eşit veya bundan daha büyük olur. Belirtilmezse sistem, uygulamanın maksimum API seviyesi olmadığını varsayar. Sistemin bu özelliği nasıl işlediği hakkında daha fazla bilgi için bu özelliğin açıklamasını okuyun.
Bir uygulamanın manifest dosyasında belirtildiğinde, <uses-sdk> öğesi şunun gibi görünebilir:
<manifest> <uses-sdk android:minSdkVersion="5" /> ... </manifest>
Bir uygulamanın android:minSdkVersion ürününde API düzeyi belirtmesinin temel nedeni, Android sistemine belirtilen API düzeyinde sunulan API'leri kullandığını bildirmektir.
Uygulama bir şekilde daha düşük API seviyesine sahip bir platforma yüklenirse çalışma zamanında mevcut olmayan API'lere erişmeye çalıştığında kilitlenir. Gereken en düşük API düzeyi, hedef cihazdaki platform sürümünden yüksek olduğunda sistem, uygulamanın yüklenmesine izin vermeyerek bu sonucu önler.
Geliştirme sürecinde dikkat edilmesi gereken noktalar
Aşağıdaki bölümlerde, uygulamanızı geliştirirken göz önünde bulundurmanız gereken API düzeyiyle ilgili bilgiler verilmektedir.
Uygulama ileriye dönük uyumluluğu
Android uygulamaları genellikle Android platformunun yeni sürümleriyle uyumludur.
Çerçeve API'sinde yapılan değişikliklerin neredeyse tümü eklemeli olduğundan, API'nin herhangi bir sürümü kullanılarak geliştirilen bir Android uygulaması, API düzeyinde belirtildiği şekilde Android platformunun sonraki sürümleriyle ve daha yüksek API düzeyleriyle ileriye dönük uyumludur. Uygulama, daha sonra herhangi bir nedenle API'nin bir parçasının kaldırıldığı izole durumlar dışında, Android platformunun sonraki tüm sürümlerinde çalışabilir.
Android destekli birçok cihaz kablosuz (OTA) sistem güncellemelerini aldığından ileriye dönük uyumluluk önemlidir. Kullanıcı, uygulamanızı yükleyip başarıyla kullanabilir, ardından daha sonra Android platformunun yeni bir sürümüne OTA güncellemesi alabilir. Güncelleme yüklendikten sonra uygulamanız, ortamın yeni bir çalışma zamanı sürümünde çalışır ancak uygulamanızın kullandığı API'ye ve sistem özelliklerine hâlâ sahip olan bir sürüm çalışır.
API'nin altındaki değişiklikler (temel sistemdekiler gibi), uygulamanızı yeni ortamda çalıştırıldığında etkileyebilir. Uygulama geliştiricisi olarak sizin, uygulamanın her sistem ortamında nasıl göründüğünü ve nasıl davrandığını anlamanız önemlidir.
Android SDK'sı, uygulamanızı Android platformunun çeşitli sürümlerinde test etmenize yardımcı olmak için indirebileceğiniz birden çok platform içerir. Her platformda, uygulamanızı test etmek için ortalama görüntüleme süresinde çalıştırabileceğiniz uyumlu bir sistem görüntüsü bulunur.
Uygulama geriye dönük uyumluluğu
Android uygulamaları, Android platformunun derlendikleri sürümden daha eski sürümleriyle geriye dönük uyumlu olmayabilir.
Android platformunun her yeni sürümü, uygulamalara yeni platform özelliklerine erişim sağlayan veya mevcut API parçalarının yerini alan API'ler gibi yeni çerçeve API'leri içerebilir. Uygulamalar, API düzeyinde belirtilen şekilde yeni platformda ve platformun sonraki sürümlerinde çalışırken yeni API'lere erişebilir. Ancak platformun önceki sürümleri yeni API'leri içermediğinden, yeni API'leri kullanan uygulamalar bu platformlarda çalışamaz.
Android destekli bir cihazın platformun önceki bir sürümüne indirgenme ihtimali olmasa da, sahada platformun önceki sürümlerini çalıştıran pek çok cihaz bulunma olasılığı yüksektir. OTA güncellemeleri alan cihazlarda bile bazıları gecikebilir ve uzun bir süre boyunca güncelleme alamayabilir.
Platform sürümü ve API düzeyi seçin
Uygulamanızı geliştirirken uygulamayı derlerken kullandığınız platform sürümünü seçersiniz. Genel olarak uygulamanızı, uygulamanızın destekleyebileceği platformun mümkün olan en düşük sürümüne göre derleyin.
Uygulamayı ardışık olarak daha düşük olan derleme hedeflerine göre derleyerek mümkün olan en düşük platform sürümünü belirleyebilirsiniz. En düşük sürümü belirledikten sonra, ilgili platform sürümünü ve API düzeyini kullanarak bir ortalama görüntüleme süresi oluşturun ve uygulamanızı tam olarak test edin. Uygulamanın manifest dosyasında bir android:minSdkVersion özelliği tanımlayıp değerini platform sürümünün API düzeyine ayarladığınızdan emin olun.
Minimum API düzeyi belirleme
En son platform sürümünde sunulan API'leri veya sistem özelliklerini kullanan bir uygulama derlerseniz android:minSdkVersion özelliğini en son platform sürümünün API düzeyine ayarlayın. Böylece kullanıcılar, yalnızca cihazlarında Android platformunun uyumlu bir sürümünü çalıştırıyorlarsa uygulamanızı yükleyebilirler. Bu da uygulamanızın kullanıcıların cihazlarında düzgün çalışmasını sağlamaya yardımcı olur.
Uygulamanız en son platform sürümünde sunulan API'leri kullanıyorsa ancak android:minSdkVersion özelliği beyan etmiyorsa uygulama, platformun en son sürümünü çalıştıran cihazlarda düzgün şekilde çalışır ancak platformun önceki sürümlerini çalıştıran cihazlarda çalışmaz. İkinci durumda uygulama, çalışma zamanında önceki sürümlerde mevcut olmayan API'leri kullanmaya çalışırken kilitlenir.
Daha yüksek API seviyeleriyle test etme
Uygulamanızı derledikten sonra, uygulamanın android:minSdkVersion özelliğinde belirtilen platformda test ettiğinizden emin olun. Bunu yapmak için uygulamanızın ihtiyaç duyduğu platform sürümünü kullanan bir ortalama görüntüleme süresi (AVD) oluşturun. Ayrıca ileriye dönük uyumluluğu kontrol etmek için uygulamayı, uygulamanız tarafından kullanılandan daha yüksek bir API düzeyi kullanan tüm platformlarda çalıştırıp test edin.
Android SDK, en son sürüm de dahil olmak üzere kullanabileceğiniz birden çok platform sürümü içerir ve gerektiğinde diğer platform sürümlerini indirmek için kullanabileceğiniz bir güncelleme aracı sağlar.
Güncelleyiciye erişmek için <sdk>/tools dizininde bulunan android komut satırı aracını kullanın. android sdk komutunu çalıştırarak SDK güncelleyiciyi başlatabilirsiniz. android.bat (Windows) veya android (OS X/Linux) dosyasını da çift tıklayabilirsiniz.
Uygulamanızı emülatörde farklı platform sürümlerinde çalıştırmak üzere test etmek istediğiniz her platform sürümü için bir ortalama görüntüleme süresi (AVD) oluşturun. Ortalama görüntüleme süresi (AVD) hakkında daha fazla bilgi için Sanal cihazlar oluşturma ve yönetme başlıklı makaleye göz atın. Test için fiziksel bir cihaz kullanıyorsanız çalıştırıldığı Android platformunun API düzeyini bildiğinizden emin olun. Platform sürümlerinin ve API seviyelerinin listesi için bu belgedeki tabloya bakın.
Referans belgelerini API düzeyine göre filtreleyin
Android platformu referans belgeleri sayfalarında, her sayfanın sol üst kısmında "API düzeyi" denetimi bulunur. Bu denetimi, manifest dosyasının android:minSdkVersion özelliğinde belirttiği API düzeyine bağlı olarak yalnızca uygulamanız tarafından gerçekten erişilebilen API bölümleriyle ilgili belgeleri göstermek için kullanabilirsiniz.
Filtrelemeyi kullanmak için menüden uygulamanız tarafından belirtilen API seviyesini seçin. Daha sonraki bir API düzeyinde sunulan API'ler daha sonra devre dışı bırakılır ve uygulamanız tarafından erişilemeyeceği için içerikleri maskelenir.
Belgelerde API düzeyine göre filtre uygulamak, her API düzeyinde sunulan yeni veya kullanıma sunulan öğelerin görünümünü sağlamaz. Bu API, belirli bir API düzeyiyle ilişkilendirilmiş API'nin tamamını görüntülemenin bir yolunu sağlar ve sonraki API düzeylerinde sunulan API öğelerini hariç tutar.
Belgelerin tamamını görüntülemeye dönmek için API düzeyi menüsünün üst kısmında REL'i seçin. API seviyesinde filtreleme varsayılan olarak devre dışıdır. Böylece API seviyesinden bağımsız olarak çerçeve API'nin tamamını görüntüleyebilirsiniz.
Bağımsız API öğeleri için referans belgelerinde, her bir öğenin tanıtıldığı API düzeyi belirtilir. Paketler ve sınıflar için API düzeyi, her belge sayfasındaki içerik alanının sağ üst köşesinde "API düzeyinde eklendi" olarak belirtilir. Sınıf üyeleri için API düzeyi, ayrıntılı açıklama başlıklarında sağ kenar boşluğunda belirtilir.