<uses-sdk>

Google Play, आपके ऐप्लिकेशन मेनिफ़ेस्ट में बताए गए <uses-sdk> एट्रिब्यूट का इस्तेमाल करके, आपके ऐप्लिकेशन को उन डिवाइसों से फ़िल्टर करता है जो प्लैटफ़ॉर्म के वर्शन की ज़रूरी शर्तों को पूरा नहीं करते. इन एट्रिब्यूट को सेट करने से पहले, पक्का करें कि आपको Google Play के फ़िल्टर के बारे में जानकारी हो.

सिंटैक्स:

<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />

इसमें शामिल है:

<manifest>

विवरण:

इसकी मदद से, यह बताया जा सकता है कि कोई ऐप्लिकेशन, Android प्लैटफ़ॉर्म के एक या इससे ज़्यादा वर्शन के साथ काम करता है या नहीं. इसके लिए, एपीआई लेवल के पूर्णांक का इस्तेमाल किया जाता है. किसी ऐप्लिकेशन के एपीआई लेवल की तुलना, किसी Android सिस्टम के एपीआई लेवल से की जाती है. यह लेवल, अलग-अलग Android डिवाइसों के लिए अलग-अलग हो सकता है.

नाम के बावजूद, इस एलिमेंट का इस्तेमाल एपीआई लेवल बताने के लिए किया जाता है, न कि सॉफ़्टवेयर डेवलपमेंट किट (एसडीके) या Android प्लैटफ़ॉर्म के वर्शन नंबर के लिए. एपीआई लेवल हमेशा एक सिंगल इंटीजर होता है. एपीआई लेवल को उससे जुड़े Android वर्शन नंबर से नहीं निकाला जा सकता. उदाहरण के लिए, यह मेजर वर्शन या मेजर और माइनर वर्शन के योग के बराबर नहीं होता.

यह तय नहीं किया जा सकता कि कोई ऐप्लिकेशन, SDK टूल के किसी माइनर वर्शन को टारगेट करता है या उसे इसकी ज़रूरत है.

अपने ऐप्लिकेशन का वर्शन तय करने के बारे में भी पढ़ें.

एट्रिब्यूट:

android:minSdkVersion

ऐप्लिकेशन को चलाने के लिए, ज़रूरी कम से कम एपीआई लेवल को बताने वाला एक पूर्णांक. अगर सिस्टम का एपीआई लेवल, इस एट्रिब्यूट में बताई गई वैल्यू से कम है, तो Android सिस्टम उपयोगकर्ता को ऐप्लिकेशन इंस्टॉल करने से रोकता है. इस एट्रिब्यूट की वैल्यू हमेशा सबमिट करें.

चेतावनी: अगर आपने इस एट्रिब्यूट के बारे में नहीं बताया है, तो सिस्टम डिफ़ॉल्ट वैल्यू "1" मान लेता है. इससे पता चलता है कि आपका ऐप्लिकेशन, Android के सभी वर्शन के साथ काम करता है. अगर ऐसा नहीं है और आपने सही minSdkVersion का एलान नहीं किया है, तो एपीआई लेवल के साथ काम न करने वाले सिस्टम पर इंस्टॉल किए जाने पर, ऐप्लिकेशन रनटाइम के दौरान क्रैश हो जाता है. ऐसा तब होता है, जब वह उन एपीआई को ऐक्सेस करने की कोशिश करता है जो उपलब्ध नहीं हैं. इस वजह से, minSdkVersion एट्रिब्यूट में सही एपीआई लेवल का एलान करना ज़रूरी है.

android:targetSdkVersion

यह एक पूर्णांक होता है, जो उस एपीआई लेवल को दिखाता है जिसे ऐप्लिकेशन टारगेट करता है. अगर यह सेट नहीं है, तो डिफ़ॉल्ट वैल्यू minSdkVersion के बराबर होती है.

इस एट्रिब्यूट से सिस्टम को पता चलता है कि आपने टारगेट वर्शन के हिसाब से टेस्ट किया है. साथ ही, सिस्टम आपके ऐप्लिकेशन को टारगेट वर्शन के साथ काम करने लायक बनाए रखने के लिए, साथ काम करने की सुविधा चालू नहीं करता. ऐप्लिकेशन अब भी इससे पहले के वर्शन (minSdkVersion तक) पर काम कर सकता है.

Android के हर नए वर्शन के साथ, कुछ सुविधाओं के काम करने के तरीके और उनके दिखने के तरीके में बदलाव हो सकता है. हालांकि, अगर प्लैटफ़ॉर्म का एपीआई लेवल, आपके ऐप्लिकेशन के targetSdkVersion से तय किए गए वर्शन से ज़्यादा है, तो सिस्टम, साथ काम करने की सुविधा चालू कर सकता है. इससे आपका ऐप्लिकेशन आपकी उम्मीद के मुताबिक काम करता रहेगा. साथ काम करने वाले ऐसे व्यवहारों को बंद किया जा सकता है. इसके लिए, targetSdkVersion को उस प्लैटफ़ॉर्म के एपीआई लेवल से मैच करना होगा जिस पर यह चल रहा है.

उदाहरण के लिए, इस वैल्यू को "11" या इससे ज़्यादा पर सेट करने से, सिस्टम आपके ऐप्लिकेशन पर Holo डिफ़ॉल्ट थीम लागू कर सकता है. ऐसा तब होता है, जब ऐप्लिकेशन Android 3.0 या इसके बाद के वर्शन पर चल रहा हो. साथ ही, बड़ी स्क्रीन पर चलने के दौरान स्क्रीन कंपैटबिलिटी मोड को बंद कर देता है. ऐसा इसलिए होता है, क्योंकि एपीआई लेवल 11 के लिए सहायता, बड़ी स्क्रीन के लिए भी काम करती है.

इस एट्रिब्यूट के लिए सेट की गई वैल्यू के आधार पर, सिस्टम कई तरह के कंपैटिबिलिटी बिहेवियर चालू कर सकता है. इनमें से कई व्यवहारों के बारे में, Build.VERSION_CODES रेफ़रंस में प्लैटफ़ॉर्म के संबंधित वर्शन के हिसाब से बताया गया है.

Android के हर रिलीज़ के साथ अपने ऐप्लिकेशन को बनाए रखने के लिए, इस एट्रिब्यूट की वैल्यू को बढ़ाकर नए एपीआई लेवल के मुताबिक करें. इसके बाद, प्लैटफ़ॉर्म के संबंधित वर्शन पर अपने ऐप्लिकेशन की अच्छी तरह से जांच करें.

एपीआई लेवल 4 में लॉन्च किया गया

android:maxSdkVersion

यह एक पूर्णांक होता है, जो उस ज़्यादा से ज़्यादा एपीआई लेवल को तय करता है जिस पर ऐप्लिकेशन को चलाने के लिए डिज़ाइन किया गया है.

Android 1.5, 1.6, 2.0, और 2.0.1 में, सिस्टम इस एट्रिब्यूट की वैल्यू की जांच करता है. ऐसा ऐप्लिकेशन इंस्टॉल करते समय और सिस्टम अपडेट के बाद, ऐप्लिकेशन की फिर से पुष्टि करते समय किया जाता है. दोनों ही मामलों में, अगर ऐप्लिकेशन का maxSdkVersion एट्रिब्यूट, सिस्टम के इस्तेमाल किए जा रहे एपीआई लेवल से कम है, तो सिस्टम ऐप्लिकेशन को इंस्टॉल नहीं होने देता. सिस्टम अपडेट के बाद फिर से पुष्टि करने पर, यह आपके ऐप्लिकेशन को डिवाइस से हटा देता है.

सिस्टम अपडेट के बाद, यह एट्रिब्यूट आपके ऐप्लिकेशन पर कैसे असर डाल सकता है, यह समझने के लिए यहां दिया गया उदाहरण देखें:

अपने मेनिफ़ेस्ट में maxSdkVersion="5" का एलान करने वाला ऐप्लिकेशन, Google Play पर पब्लिश किया गया हो. कोई उपयोगकर्ता, Android 1.6 (एपीआई लेवल 4) पर चलने वाले डिवाइस पर ऐप्लिकेशन डाउनलोड और इंस्टॉल करता है. कुछ हफ़्तों के बाद, उपयोगकर्ता को Android 2.0 (एपीआई लेवल 5) पर ओवर-द-एयर सिस्टम अपडेट मिलता है. अपडेट इंस्टॉल होने के बाद, सिस्टम ऐप्लिकेशन के maxSdkVersion की जांच करता है और उसकी फिर से पुष्टि करता है.

ऐप्लिकेशन सामान्य रूप से काम करता है. हालांकि, कुछ समय बाद डिवाइस को एक और सिस्टम अपडेट मिलता है. इस बार, Android 2.0.1 (एपीआई लेवल 6) पर अपडेट किया जाता है. अपडेट के बाद, सिस्टम ऐप्लिकेशन की फिर से पुष्टि नहीं कर सकता, क्योंकि सिस्टम का अपना एपीआई लेवल (6) अब ऐप्लिकेशन के लिए तय किए गए ज़्यादा से ज़्यादा एपीआई लेवल (5) से ज़्यादा है. सिस्टम, उपयोगकर्ता को ऐप्लिकेशन दिखने से रोकता है. इससे, ऐप्लिकेशन डिवाइस से हट जाता है.

चेतावनी: हमारा सुझाव है कि इस एट्रिब्यूट का एलान न करें. सबसे पहले, Android प्लैटफ़ॉर्म के नए वर्शन रिलीज़ होने पर, उन पर अपने ऐप्लिकेशन को डिप्लॉय होने से रोकने के लिए, एट्रिब्यूट को सेट करने की ज़रूरत नहीं है. प्लैटफ़ॉर्म के नए वर्शन, पुराने सिस्टम के साथ पूरी तरह काम करते हैं. आपका ऐप्लिकेशन नए वर्शन पर ठीक से काम करता है. हालांकि, इसके लिए ज़रूरी है कि वह सिर्फ़ स्टैंडर्ड एपीआई का इस्तेमाल करे और डेवलपमेंट के सबसे सही तरीकों का पालन करे. दूसरा, कुछ मामलों में एट्रिब्यूट का एलान करने से, सिस्टम को ज़्यादा एपीआई लेवल पर अपडेट करने के बाद, आपके ऐप्लिकेशन को उपयोगकर्ताओं के डिवाइसों से हटाया जा सकता है. जिन डिवाइसों पर आपका ऐप्लिकेशन इंस्टॉल किया जा सकता है उनमें से ज़्यादातर डिवाइसों को समय-समय पर, ओवर द एयर सिस्टम अपडेट मिलते हैं. इसलिए, इस एट्रिब्यूट को सेट करने से पहले, अपने ऐप्लिकेशन पर उनके असर के बारे में सोचें.

एपीआई लेवल 4 में लॉन्च किया गया

Android के कुछ वर्शन (Android 2.0.1 के बाद के वर्शन), इंस्टॉल करने या फिर से पुष्टि करने के दौरान, maxSdkVersion एट्रिब्यूट की जांच नहीं करते या उसे लागू नहीं करते. हालांकि, Google Play अब भी इस एट्रिब्यूट का इस्तेमाल फ़िल्टर के तौर पर करता है. ऐसा तब होता है, जब उपयोगकर्ताओं को डाउनलोड के लिए उपलब्ध ऐप्लिकेशन दिखाए जाते हैं.

पहली बार इसमें दिखाया गया:

एपीआई लेवल 1

एपीआई लेवल क्या है?

एपीआई लेवल एक पूर्णांक वैल्यू होती है, जो Android प्लैटफ़ॉर्म के किसी वर्शन से मिलने वाले फ़्रेमवर्क एपीआई के बदलाव की खास तौर पर पहचान करती है.

Android प्लैटफ़ॉर्म, एक फ़्रेमवर्क एपीआई उपलब्ध कराता है. ऐप्लिकेशन इसका इस्तेमाल करके, Android सिस्टम के साथ इंटरैक्ट कर सकते हैं. फ़्रेमवर्क एपीआई में ये शामिल हैं:

• पैकेज और क्लास का मुख्य सेट
• मेनिफ़ेस्ट फ़ाइल का एलान करने के लिए, एक्सएमएल एलिमेंट और एट्रिब्यूट का सेट
• संसाधनों के बारे में बताने और उन्हें ऐक्सेस करने के लिए, एक्सएमएल एलिमेंट और एट्रिब्यूट का सेट
• इंटेंट का सेट
• अनुमतियों का एक सेट, जिसके लिए ऐप्लिकेशन अनुरोध कर सकते हैं. साथ ही, सिस्टम में शामिल अनुमतियों को लागू करने की सुविधा

Android प्लैटफ़ॉर्म के हर नए वर्शन में, Android ऐप्लिकेशन फ़्रेमवर्क एपीआई के अपडेट शामिल हो सकते हैं.

फ़्रेमवर्क एपीआई में किए गए अपडेट इस तरह से डिज़ाइन किए गए हैं कि नया एपीआई, एपीआई के पुराने वर्शन के साथ काम करता रहे. इसका मतलब है कि एपीआई में ज़्यादातर बदलाव, नई या बदली हुई सुविधाओं को जोड़ने के लिए किए जाते हैं. एपीआई के कुछ हिस्सों को अपग्रेड करने पर, बदले गए पुराने हिस्सों को बंद कर दिया जाता है. हालांकि, उन्हें हटाया नहीं जाता, ताकि मौजूदा ऐप्लिकेशन अब भी उनका इस्तेमाल कर सकें.

बहुत कम मामलों में, एपीआई के कुछ हिस्सों में बदलाव किया जाता है या उन्हें हटा दिया जाता है. हालांकि, आम तौर पर ऐसे बदलाव सिर्फ़ एपीआई को बेहतर बनाने और ऐप्लिकेशन या सिस्टम की सुरक्षा के लिए ज़रूरी होते हैं. पिछले वर्शन के एपीआई के अन्य सभी हिस्सों को बिना किसी बदलाव के आगे बढ़ाया जाता है.

Android प्लैटफ़ॉर्म जो फ़्रेमवर्क एपीआई उपलब्ध कराता है उसे एपीआई लेवल नाम के पूर्णांक आइडेंटिफ़ायर का इस्तेमाल करके तय किया जाता है. Android प्लैटफ़ॉर्म का हर वर्शन, सिर्फ़ एक एपीआई लेवल के साथ काम करता है. हालांकि, यह पहले के सभी एपीआई लेवल (एपीआई लेवल 1 तक) के साथ भी काम करता है. Android प्लैटफ़ॉर्म की शुरुआती रिलीज़ में एपीआई लेवल 1 उपलब्ध कराया गया था. इसके बाद की रिलीज़ में, एपीआई लेवल को बढ़ाया गया है. रिलीज़ से पहले उपलब्ध कराए गए झलक वाले SDK टूल में, ऐसे एपीआई जोड़े या हटाए जाते हैं जो प्लैटफ़ॉर्म के हिसाब से स्टेबल नहीं होते. इन्हें एपीआई लेवल नंबर के बजाय, "एपीआई को डेवलप किया जा रहा है" के तौर पर मार्क किया जाता है.

नीचे दी गई टेबल में, Android प्लैटफ़ॉर्म के हर वर्शन के साथ काम करने वाले एपीआई लेवल की जानकारी दी गई है. हर वर्शन पर काम करने वाले डिवाइसों की संख्या के बारे में जानकारी पाने के लिए, डिस्ट्रिब्यूशन डैशबोर्ड देखें.

डेवलप किए जा रहे एपीआई

Android API के रेफ़रंस दस्तावेज़ में, रिलीज़ से पहले के SDK टूल में जोड़े गए या बंद किए गए एपीआई को एपीआई लेवल नंबर के बजाय, "एपीआई पर काम चल रहा है" के तौर पर मार्क किया जाता है. यह लेबल, "इसमें जोड़ा गया" और "इसमें बंद किया गया" दोनों सूचनाओं पर तब तक लागू होता है, जब तक एसडीके प्लैटफ़ॉर्म के हिसाब से स्टेबल नहीं हो जाता और उसे फ़ाइनल मेजर या माइनर एपीआई लेवल नहीं मिल जाता. डेवलप किए जा रहे एपीआई की ये विशेषताएं होती हैं:

• रिलीज़ से पहले की झलक की स्थिति: एपीआई लेवल तय होने से पहले, एपीआई को जोड़ने या बंद करने की प्रोसेस, बीटा या कैनरी झलक वाले एसडीके की रिलीज़ का हिस्सा होती है.
• स्थिरता की कोई गारंटी नहीं है: रिलीज़ किए गए एपीआई का एक स्थायी एपीआई लेवल होता है और वे आने वाले समय में रिलीज़ होने वाले वर्शन के साथ काम करते हैं. हालांकि, डेवलप किए जा रहे एपीआई के सिग्नेचर बदल सकते हैं, उनका नाम बदला जा सकता है या उन्हें एसडीके के रिलीज़ होने से पहले पूरी तरह से हटाया जा सकता है.

रनटाइम के दौरान, डेवलप किए जा रहे एपीआई की जांच करना (PREVIEW_SDK_INT)

डेवलप किए जा रहे एपीआई, लॉन्च से पहले झलक देखने के लिए बनाए गए वर्शन के बीच बदल सकते हैं या गायब हो सकते हैं. इसलिए, रिलीज़ नहीं किए गए एपीआई के कॉल को सुरक्षित रखने के लिए, कभी भी 'इससे ज़्यादा या इसके बराबर' वाली जांच (>=) का इस्तेमाल न करें. ऐसा हो सकता है कि झलक 1 में मौजूद किसी एपीआई में, झलक 2 में बदलाव किया जाए या उसे हटा दिया जाए.

इसके बजाय, झलक के लिए उपलब्ध सुविधाओं के साथ एक्सपेरिमेंट करने वाले ऐप्लिकेशन को Build.VERSION.PREVIEW_SDK_INT वैल्यू की जांच करनी चाहिए. इससे यह पता चलता है कि झलक के लिए उपलब्ध सुविधा का जो वर्शन ऐप्लिकेशन में इस्तेमाल किया गया है वह पूरी तरह से एक जैसा (==) है या नहीं:

• फ़ाइनल, प्रोडक्शन बिल्ड, और रिलीज़ पर, Build.VERSION.PREVIEW_SDK_INT हमेशा 0 होता है.
• झलक वाले बिल्ड पर, हर रिलीज़ के लिए PREVIEW_SDK_INT यूनीक होता है.

Android में एपीआई लेवल के इस्तेमाल

एपीआई लेवल आइडेंटिफ़ायर, उपयोगकर्ताओं और ऐप्लिकेशन डेवलपर को सबसे अच्छा अनुभव देने में अहम भूमिका निभाता है:

• इससे Android प्लैटफ़ॉर्म को यह बताने में मदद मिलती है कि वह फ़्रेमवर्क एपीआई के ज़्यादा से ज़्यादा किस वर्शन के साथ काम करता है.
• इससे ऐप्लिकेशन, फ़्रेमवर्क एपीआई के उस बदलाव के बारे में बता सकते हैं जिसकी उन्हें ज़रूरत है.
• यह सिस्टम को उपयोगकर्ता के डिवाइस पर ऐप्लिकेशन इंस्टॉल करने की अनुमति देता है, ताकि ऐसे ऐप्लिकेशन इंस्टॉल न हों जो डिवाइस के वर्शन के साथ काम नहीं करते.

Android प्लैटफ़ॉर्म का हर वर्शन, अपने एपीआई लेवल आइडेंटिफ़ायर को इंटरनल तौर पर, Android सिस्टम में ही सेव करता है.

ऐप्लिकेशन, फ़्रेमवर्क एपीआई—<uses-sdk>—से मिले मेनिफ़ेस्ट एलिमेंट का इस्तेमाल कर सकते हैं. इससे, एपीआई के कम से कम और ज़्यादा से ज़्यादा लेवल के बारे में बताया जा सकता है. इन लेवल के तहत, ऐप्लिकेशन काम कर सकते हैं. साथ ही, एपीआई के उस पसंदीदा लेवल के बारे में भी बताया जा सकता है जिसके लिए उन्हें डिज़ाइन किया गया है. इस एलिमेंट में तीन मुख्य एट्रिब्यूट होते हैं:

• android:minSdkVersion: वह कम से कम एपीआई लेवल जिस पर ऐप्लिकेशन काम कर सकता है. इसकी डिफ़ॉल्ट वैल्यू "1" होती है.
• android:targetSdkVersion: वह एपीआई लेवल जिस पर ऐप्लिकेशन को चलाने के लिए डिज़ाइन किया गया है. कुछ मामलों में, इससे ऐप्लिकेशन को टारगेट एपीआई लेवल में तय किए गए मेनिफ़ेस्ट एलिमेंट या व्यवहारों का इस्तेमाल करने की अनुमति मिलती है. इसके लिए, उसे कम से कम एपीआई लेवल के लिए तय किए गए एलिमेंट या व्यवहारों का इस्तेमाल करने की ज़रूरत नहीं होती.
• android:maxSdkVersion: वह ज़्यादा से ज़्यादा एपीआई लेवल जिस पर ऐप्लिकेशन काम कर सकता है. अहम जानकारी: इस एट्रिब्यूट का इस्तेमाल करने से पहले, इस पेज पर इस एट्रिब्यूट के बारे में जानकारी पढ़ें.

उदाहरण के लिए, किसी ऐप्लिकेशन को चलाने के लिए ज़रूरी सिस्टम एपीआई लेवल की जानकारी देने के लिए, ऐप्लिकेशन अपने मेनिफ़ेस्ट में android:minSdkVersion एट्रिब्यूट के साथ <uses-sdk> एलिमेंट शामिल करता है. android:minSdkVersion की वैल्यू, Android प्लैटफ़ॉर्म के सबसे पुराने वर्शन के एपीआई लेवल से जुड़ा पूर्णांक है. इस वर्शन पर ऐप्लिकेशन को चलाया जा सकता है.

जब कोई उपयोगकर्ता किसी ऐप्लिकेशन को इंस्टॉल करने की कोशिश करता है या सिस्टम अपडेट के बाद किसी ऐप्लिकेशन की फिर से पुष्टि करता है, तो Android सिस्टम सबसे पहले ऐप्लिकेशन के मेनिफ़ेस्ट में <uses-sdk> एट्रिब्यूट की जांच करता है. साथ ही, वैल्यू की तुलना अपने इंटरनल एपीआई लेवल से करता है. सिस्टम, इंस्टॉल करने की प्रोसेस सिर्फ़ तब शुरू करता है, जब ये शर्तें पूरी होती हैं:

• अगर android:minSdkVersion एट्रिब्यूट का एलान किया गया है, तो इसकी वैल्यू, सिस्टम के एपीआई लेवल के पूर्णांक से कम या उसके बराबर होनी चाहिए. अगर एलान नहीं किया जाता है, तो सिस्टम यह मान लेता है कि ऐप्लिकेशन को एपीआई लेवल 1 की ज़रूरत है.
• अगर android:maxSdkVersion एट्रिब्यूट का एलान किया गया है, तो इसकी वैल्यू सिस्टम के एपीआई लेवल के पूर्णांक के बराबर या उससे ज़्यादा होनी चाहिए. अगर इसका एलान नहीं किया जाता है, तो सिस्टम यह मान लेता है कि ऐप्लिकेशन के लिए कोई एपीआई लेवल तय नहीं किया गया है. सिस्टम इस एट्रिब्यूट को कैसे मैनेज करता है, इस बारे में ज़्यादा जानने के लिए, इस एट्रिब्यूट की जानकारी पढ़ें.

किसी ऐप्लिकेशन के मेनिफ़ेस्ट में एलान किए जाने पर, <uses-sdk> एलिमेंट ऐसा दिख सकता है:

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

android:minSdkVersion में किसी ऐप्लिकेशन के एपीआई लेवल का एलान करने की मुख्य वजह, Android सिस्टम को यह बताना है कि वह एपीआई लेवल में शामिल किए गए एपीआई का इस्तेमाल करता है.

अगर ऐप्लिकेशन किसी तरह कम एपीआई लेवल वाले प्लैटफ़ॉर्म पर इंस्टॉल हो जाता है, तो रनटाइम के दौरान वह क्रैश हो जाता है. ऐसा तब होता है, जब वह उन एपीआई को ऐक्सेस करने की कोशिश करता है जो मौजूद नहीं हैं. सिस्टम इस समस्या को रोकने के लिए, ऐप्लिकेशन को इंस्टॉल नहीं होने देता. ऐसा तब होता है, जब ऐप्लिकेशन के लिए ज़रूरी सबसे कम एपीआई लेवल, टारगेट डिवाइस पर मौजूद प्लैटफ़ॉर्म के वर्शन से ज़्यादा हो.

डेवलपमेंट के दौरान ध्यान देने वाली बातें

यहां दिए गए सेक्शन में, एपीआई लेवल से जुड़ी जानकारी दी गई है. ऐप्लिकेशन डेवलप करते समय, आपको इस जानकारी को ध्यान में रखना चाहिए.

ऐप्लिकेशन के साथ काम करने की सुविधा

Android ऐप्लिकेशन, आम तौर पर Android प्लैटफ़ॉर्म के नए वर्शन के साथ काम करते हैं.

फ़्रेमवर्क एपीआई में किए जाने वाले ज़्यादातर बदलाव, एपीआई में नई सुविधाएं जोड़ने के लिए होते हैं. इसलिए, एपीआई के किसी भी वर्शन का इस्तेमाल करके बनाया गया Android ऐप्लिकेशन, Android प्लैटफ़ॉर्म के बाद के वर्शन और ज़्यादा एपीआई लेवल के साथ काम करता है. यह ऐप्लिकेशन, Android प्लैटफ़ॉर्म के बाद के सभी वर्शन पर चल सकता है. हालांकि, कुछ मामलों में ऐसा नहीं होता. जैसे, जब ऐप्लिकेशन किसी ऐसे एपीआई का इस्तेमाल करता है जिसे बाद में किसी वजह से हटा दिया गया हो.

फ़ॉरवर्ड कंपैटबिलिटी ज़रूरी है, क्योंकि Android की सुविधा वाले कई डिवाइसों को ओवर-द-एयर (ओटीए) सिस्टम अपडेट मिलते हैं. ऐसा हो सकता है कि उपयोगकर्ता आपके ऐप्लिकेशन को इंस्टॉल करके, उसे इस्तेमाल कर पाए. इसके बाद, उसे Android प्लैटफ़ॉर्म के नए वर्शन का ओटीए अपडेट मिले. अपडेट इंस्टॉल होने के बाद, आपका ऐप्लिकेशन एनवायरमेंट के नए रनटाइम वर्शन में चलता है. हालांकि, इसमें अब भी वे एपीआई और सिस्टम की सुविधाएं मौजूद होती हैं जिन पर आपका ऐप्लिकेशन निर्भर करता है.

एपीआई के नीचे किए गए बदलाव, जैसे कि सिस्टम में किए गए बदलाव, नए एनवायरमेंट में चलाए जाने पर आपके ऐप्लिकेशन पर असर डाल सकते हैं. ऐप्लिकेशन डेवलपर के तौर पर, आपके लिए यह समझना ज़रूरी है कि हर सिस्टम एनवायरमेंट में ऐप्लिकेशन कैसा दिखता है और कैसे काम करता है.

Android प्लैटफ़ॉर्म के अलग-अलग वर्शन पर अपने ऐप्लिकेशन की जांच करने में आपकी मदद करने के लिए, Android SDK में कई प्लैटफ़ॉर्म शामिल हैं. इन्हें डाउनलोड किया जा सकता है. हर प्लैटफ़ॉर्म में, साथ काम करने वाली सिस्टम इमेज शामिल होती है. इसे एवीडी में चलाकर, अपने ऐप्लिकेशन की जांच की जा सकती है.

ऐप्लिकेशन के पुराने सिस्टम के साथ काम करने की सुविधा

यह ज़रूरी नहीं है कि Android ऐप्लिकेशन, Android प्लैटफ़ॉर्म के उन वर्शन के साथ काम करें जो उस वर्शन से पुराने हैं जिसके लिए उन्हें कंपाइल किया गया था.

Android प्लैटफ़ॉर्म के हर नए वर्शन में, नए फ़्रेमवर्क एपीआई शामिल हो सकते हैं. जैसे, वे एपीआई जो ऐप्लिकेशन को नए प्लैटफ़ॉर्म की सुविधाओं का ऐक्सेस देते हैं या मौजूदा एपीआई के हिस्सों को बदलते हैं. नए एपीआई, नए प्लैटफ़ॉर्म पर चलने वाले ऐप्लिकेशन के लिए उपलब्ध होते हैं. साथ ही, ये प्लैटफ़ॉर्म के बाद के वर्शन पर चलने वाले ऐप्लिकेशन के लिए भी उपलब्ध होते हैं. ऐसा एपीआई लेवल के हिसाब से होता है. हालांकि, प्लैटफ़ॉर्म के पुराने वर्शन में नए एपीआई शामिल नहीं होते हैं. इसलिए, नए एपीआई का इस्तेमाल करने वाले ऐप्लिकेशन उन प्लैटफ़ॉर्म पर नहीं चल सकते.

हालांकि, Android डिवाइस को प्लैटफ़ॉर्म के पिछले वर्शन पर डाउनग्रेड किए जाने की संभावना नहीं है, लेकिन यह समझना ज़रूरी है कि ऐसे कई डिवाइस हो सकते हैं जो प्लैटफ़ॉर्म के पिछले वर्शन पर काम करते हों. ओटीए अपडेट पाने वाले कुछ डिवाइसों में, अपडेट मिलने में देरी हो सकती है. साथ ही, हो सकता है कि कुछ डिवाइसों को लंबे समय तक अपडेट न मिले.

कोई प्लैटफ़ॉर्म वर्शन और एपीआई लेवल चुनें

ऐप्लिकेशन बनाते समय, आपको प्लैटफ़ॉर्म का वह वर्शन चुनना होता है जिसके लिए ऐप्लिकेशन को कंपाइल करना है. आम तौर पर, अपने ऐप्लिकेशन को प्लैटफ़ॉर्म के सबसे कम वर्शन के हिसाब से कंपाइल करें, ताकि आपका ऐप्लिकेशन उस पर काम कर सके.

ऐप्लिकेशन को लगातार कम बिल्ड टारगेट के हिसाब से कंपाइल करके, सबसे कम संभावित प्लैटफ़ॉर्म वर्शन का पता लगाया जा सकता है. सबसे पुराने वर्शन का पता लगाने के बाद, उससे जुड़े प्लैटफ़ॉर्म वर्शन और एपीआई लेवल का इस्तेमाल करके एवीडी बनाएं. इसके बाद, अपने ऐप्लिकेशन की पूरी तरह से जांच करें. ऐप्लिकेशन के मेनिफ़ेस्ट में android:minSdkVersion एट्रिब्यूट का एलान ज़रूर करें. साथ ही, इसकी वैल्यू को प्लैटफ़ॉर्म के वर्शन के एपीआई लेवल पर सेट करें.

कम से कम एपीआई लेवल का एलान करना

अगर आपने कोई ऐसा ऐप्लिकेशन बनाया है जो प्लैटफ़ॉर्म के नए वर्शन में उपलब्ध एपीआई या सिस्टम की सुविधाओं का इस्तेमाल करता है, तो android:minSdkVersion एट्रिब्यूट को प्लैटफ़ॉर्म के नए वर्शन के एपीआई लेवल पर सेट करें. ऐसा इसलिए किया जाता है, ताकि उपयोगकर्ता आपके ऐप्लिकेशन को सिर्फ़ तब इंस्टॉल कर पाएं, जब उनके डिवाइसों पर Android प्लैटफ़ॉर्म का कोई ऐसा वर्शन चल रहा हो जो आपके ऐप्लिकेशन के साथ काम करता हो. इससे यह पक्का करने में मदद मिलती है कि आपका ऐप्लिकेशन, उपयोगकर्ताओं के डिवाइसों पर ठीक से काम कर सके.

अगर आपका ऐप्लिकेशन, प्लैटफ़ॉर्म के नए वर्शन में उपलब्ध एपीआई का इस्तेमाल करता है, लेकिन android:minSdkVersion एट्रिब्यूट का एलान नहीं करता है, तो यह प्लैटफ़ॉर्म के नए वर्शन पर काम करने वाले डिवाइसों पर ठीक से काम करता है. हालांकि, यह प्लैटफ़ॉर्म के पुराने वर्शन पर काम करने वाले डिवाइसों पर ठीक से काम नहीं करता. बाद वाले मामले में, ऐप्लिकेशन रनटाइम के दौरान क्रैश हो जाता है. ऐसा तब होता है, जब वह उन एपीआई का इस्तेमाल करने की कोशिश करता है जो पुराने वर्शन पर मौजूद नहीं हैं.

ज़्यादा एपीआई लेवल के हिसाब से टेस्ट करना

अपना ऐप्लिकेशन कंपाइल करने के बाद, पक्का करें कि आपने ऐप्लिकेशन के android:minSdkVersion एट्रिब्यूट में बताए गए प्लैटफ़ॉर्म पर उसकी जांच की हो. इसके लिए, ऐसा एवीडी बनाएं जो आपके ऐप्लिकेशन के लिए ज़रूरी प्लैटफ़ॉर्म वर्शन का इस्तेमाल करता हो. इसके अलावा, फ़ॉरवर्ड-कंपैटिबिलिटी की जांच करने के लिए, ऐप्लिकेशन को उन सभी प्लैटफ़ॉर्म पर चलाएं और टेस्ट करें जो आपके ऐप्लिकेशन के एपीआई लेवल से ज़्यादा लेवल वाले एपीआई का इस्तेमाल करते हैं.

Android SDK में कई प्लैटफ़ॉर्म वर्शन शामिल हैं, जिनका इस्तेमाल किया जा सकता है. इनमें सबसे नया वर्शन भी शामिल है. साथ ही, इसमें एक अपडेटर टूल भी मिलता है. इसका इस्तेमाल करके, ज़रूरत के हिसाब से अन्य प्लैटफ़ॉर्म वर्शन डाउनलोड किए जा सकते हैं.

अपडेटर को ऐक्सेस करने के लिए, android कमांड-लाइन टूल का इस्तेमाल करें. यह टूल, <sdk>/tools डायरेक्ट्री में मौजूद होता है. android sdk को एक्ज़ीक्यूट करके, SDK टूल का अपडेटर लॉन्च किया जा सकता है. android.bat (Windows) या android (OS X/Linux) फ़ाइल पर दो बार क्लिक करके भी इसे खोला जा सकता है.

एम्युलेटर में अलग-अलग प्लैटफ़ॉर्म वर्शन पर अपना ऐप्लिकेशन चलाने के लिए, हर उस प्लैटफ़ॉर्म वर्शन के लिए एक एवीडी बनाएं जिसकी आपको जांच करनी है. एवीडी के बारे में ज़्यादा जानकारी के लिए, वर्चुअल डिवाइस बनाना और उन्हें मैनेज करना लेख पढ़ें. अगर टेस्टिंग के लिए किसी फ़िज़िकल डिवाइस का इस्तेमाल किया जा रहा है, तो पक्का करें कि आपको उस पर चल रहे Android प्लैटफ़ॉर्म के एपीआई लेवल की जानकारी हो. प्लैटफ़ॉर्म के वर्शन और उनके एपीआई लेवल की सूची के लिए, इस दस्तावेज़ में दी गई टेबल देखें.

एपीआई लेवल के हिसाब से रेफ़रंस दस्तावेज़ को फ़िल्टर करना

Android प्लैटफ़ॉर्म के रेफ़रंस दस्तावेज़ वाले पेजों पर, हर पेज के सबसे ऊपर बाईं ओर "एपीआई लेवल" कंट्रोल होता है. कंट्रोल का इस्तेमाल करके, एपीआई के सिर्फ़ उन हिस्सों के लिए दस्तावेज़ दिखाए जा सकते हैं जिन्हें आपका ऐप्लिकेशन ऐक्सेस कर सकता है. यह ऐप्लिकेशन के मेनिफ़ेस्ट फ़ाइल के android:minSdkVersion एट्रिब्यूट में बताए गए एपीआई लेवल पर आधारित होता है.

फ़िल्टर करने की सुविधा का इस्तेमाल करने के लिए, मेन्यू से वह एपीआई लेवल चुनें जो आपके ऐप्लिकेशन के लिए तय किया गया है. इसके बाद, बाद के एपीआई लेवल में पेश किए गए एपीआई धूसर हो जाते हैं और उनका कॉन्टेंट मास्क हो जाता है, क्योंकि वे आपके ऐप्लिकेशन के लिए ऐक्सेस नहीं किए जा सकते.

दस्तावेज़ में एपीआई लेवल के हिसाब से फ़िल्टर करने पर, यह नहीं दिखता कि हर एपीआई लेवल में क्या नया है या क्या जोड़ा गया है. इससे किसी एपीआई लेवल से जुड़े पूरे एपीआई को देखा जा सकता है. हालांकि, इसमें बाद के एपीआई लेवल में जोड़े गए एपीआई एलिमेंट शामिल नहीं होते.

पूरा दस्तावेज़ फिर से देखने के लिए, एपीआई लेवल मेन्यू में सबसे ऊपर मौजूद REL को चुनें. डिफ़ॉल्ट रूप से, एपीआई लेवल के हिसाब से फ़िल्टर करने की सुविधा बंद होती है. इससे आपको एपीआई लेवल की परवाह किए बिना, पूरा फ़्रेमवर्क एपीआई देखने की सुविधा मिलती है.

अलग-अलग एपीआई एलिमेंट के लिए रेफ़रंस दस्तावेज़ में, उस एपीआई लेवल के बारे में बताया जाता है जिस पर हर एलिमेंट को पेश किया गया है या उसे बंद कर दिया गया है. पैकेज और क्लास के लिए एपीआई लेवल को "एपीआई लेवल में जोड़ा गया" के तौर पर बताया जाता है. साथ ही, लागू होने पर, हर दस्तावेज़ पेज के कॉन्टेंट एरिया के सबसे ऊपर दाएं कोने में "एपीआई लेवल में अब काम नहीं करता" के तौर पर बताया जाता है. क्लास के सदस्यों के लिए एपीआई लेवल, उनके ब्यौरे वाले हेडर में दाईं ओर बताया जाता है. रिलीज़ से पहले एपीआई में जोड़े गए या हटाए गए ऐसे फ़ंक्शन जो प्लैटफ़ॉर्म पर स्टेबल नहीं हैं उनके लिए, इन जगहों पर एपीआई लेवल नंबर के बजाय "एपीआई पर काम चल रहा है" दिखता है.