نمای کلی مانیفست برنامه

هر پروژه برنامه باید یک فایل AndroidManifest.xml با دقیقاً همین نام در ریشه مجموعه منبع پروژه داشته باشد. فایل مانیفست اطلاعات ضروری درباره برنامه‌تان را برای ابزارهای ساخت Android، سیستم‌عامل Android، و Google Play شرح می‌دهد.

در میان بسیاری از موارد دیگر، فایل مانیفست برای اعلام موارد زیر لازم است:

• مؤلفه‌های برنامه، ازجمله همه فعالیت‌ها، سرویس‌ها، گیرنده‌های رویداد ثبت‌شده، و ارائه‌دهندگان محتوا. هر مؤلفه باید ویژگی‌های اصلی را تعریف کند، مانند نام کلاس Kotlin یا Java آن. همچنین می‌تواند قابلیت‌ها را اعلام کند، مثلاً اینکه کدام پیکربندی‌های دستگاه را می‌تواند مدیریت کند، و فیلترهای قصدی که نحوه راه‌اندازی مؤلفه را شرح می‌دهند. در بخش زیر، درباره مؤلفه‌های برنامه بیشتر بخوانید.
• اجازه‌هایی که برنامه برای دسترسی به بخش‌های محافظت‌شده سیستم یا برنامه‌های دیگر نیاز دارد. همچنین، هرگونه اجازه‌ای را که برنامه‌های دیگر برای دسترسی به محتوای این برنامه باید داشته باشند اعلام می‌کند. در بخش بعدی، درباره اجازه‌ها بیشتر بخوانید.
• ویژگی‌های سخت‌افزاری و نرم‌افزاری که برنامه نیاز دارد، که بر اینکه کدام دستگاه‌ها می‌توانند برنامه را از Google Play نصب کنند تأثیر می‌گذارد. در بخش زیر، درباره سازگاری دستگاه بیشتر بخوانید.

اگر از استودیو Android برای ساختن برنامه‌تان استفاده می‌کنید، فایل مانیفست برای شما ایجاد می‌شود و بیشتر عناصر ضروری مانیفست هنگام ساختن برنامه‌تان اضافه می‌شوند، به‌ویژه وقتی از الگوهای کد استفاده می‌کنید.

ویژگی‌های فایل

بخش‌های زیر نحوه انعکاس برخی‌از مهم‌ترین ویژگی‌های برنامه‌تان را در فایل مانیفست شرح می‌دهد.

مؤلفه‌های برنامه

برای هر جزء برنامه که در برنامه‌تان ایجاد می‌کنید، یک عنصر XML متناظر در فایل مانیفست اعلام کنید:

• <activity> برای هر زیرکلاس Activity
• <service> برای هر زیرکلاس Service
• <receiver> برای هر زیرکلاس BroadcastReceiver
• <provider> برای هر زیرکلاس ContentProvider

اگر هرکدام از این مؤلفه‌ها را بدون اعلام آن در فایل مانیفست زیرکلاس کنید، سیستم نمی‌تواند آن را راه‌اندازی کند.

نام زیرکلاس خود را با مشخصه name و بااستفاده از نام کامل بسته مشخص کنید. برای مثال، یک زیرکلاس Activity به‌صورت زیر اعلام می‌شود:

<manifest ... >
    <application ... >
        <activity android:name="com.example.myapp.MainActivity" ... >
        </activity>
    </application>
</manifest>

اما اگر اولین نویسه در مقدار name نقطه باشد، فضای نام برنامه، از ویژگی namespace فایل build.gradle در سطح ماژول، به نام پیشوند می‌شود. برای مثال، اگر فضای نام "com.example.myapp" باشد، نام فعالیت زیر به com.example.myapp.MainActivity تبدیل می‌شود:

<manifest ... >
    <application ... >
        <activity android:name=".MainActivity" ... >
            ...
        </activity>
    </application>
</manifest>

برای اطلاعات بیشتر درباره تنظیم نام بسته یا فضای نام، به تنظیم فضای نام مراجعه کنید.

اگر مؤلفه‌های برنامه‌ای دارید که در زیربسته‌ها قرار دارند، مثلاً در com.example.myapp.purchases، مقدار name باید نام‌های زیربسته ناموجود را اضافه کند، مثلاً ".purchases.PayActivity"، یا از نام بسته کاملاً واجدشرایط استفاده کند.

فیلترهای قصد

فعالیت‌ها، سرویس‌ها، و گیرنده‌های رویداد ثبت‌شده برنامه با قصدها فعال می‌شوند. هدف پیامی است که توسط شیء Intent تعریف می‌شود و کنش موردنظر برای اجرا را شرح می‌دهد، ازجمله داده‌هایی که باید روی آن‌ها کنش انجام شود، دسته مؤلفه‌ای که انتظار می‌رود کنش را انجام دهد، و دستورالعمل‌های دیگر.

وقتی برنامه‌ای قصدی را برای سیستم صادر می‌کند، سیستم براساس اظهارات فیلتر قصد در فایل مانیفست هر برنامه، مؤلفه برنامه‌ای را که می‌تواند قصد را مدیریت کند پیدا می‌کند. سیستم نمونه‌ای از عنصر منطبق را راه‌اندازی می‌کند و شیء Intent را به آن عنصر منتقل می‌کند. اگر بیش‌از یک برنامه بتواند هدف را مدیریت کند، کاربر می‌تواند انتخاب کند از کدام برنامه استفاده شود.

یک مؤلفه برنامه می‌تواند هر تعداد فیلتر قصد (تعریف‌شده با عنصر <intent-filter> ) داشته باشد، که هرکدام قابلیت متفاوتی از آن مؤلفه را توصیف می‌کنند.

برای اطلاعات بیشتر، به سند قصدها و فیلترهای قصد مراجعه کنید.

نمادها و برچسب‌ها

تعدادی از عناصر مانیفست دارای مشخصه‌های icon و label هستند که به‌ترتیب برای نمایش نماد کوچک و برچسب نوشتاری به کاربران برای مؤلفه برنامه مربوطه استفاده می‌شوند.

در همه موارد، نماد و برچسبی که در عنصر والد تنظیم شده است، به مقدار پیش‌فرض icon و label برای همه عناصر فرزند تبدیل می‌شود. برای مثال، نماد و برچسبی که در عنصر <application> تنظیم شده‌اند، نماد و برچسب پیش‌فرض برای هریک از مؤلفه‌های برنامه، مانند همه فعالیت‌ها، هستند.

نماد و برچسبی که در <intent-filter> مؤلفه تنظیم شده است، هرگاه آن مؤلفه به‌عنوان گزینه‌ای برای برآورده کردن قصد ارائه شود، به کاربر نشان داده می‌شود. به‌طور پیش‌فرض، این نماد از هر نمادی که برای مؤلفه والد اعلام شده باشد، یعنی عنصر <activity> یا <application>، به ارث می‌رسد.

اگر فیلتر قصد کنش منحصربه‌فردی ارائه می‌دهد که می‌خواهید آن را در کادر گفتگوی انتخابگر بهتر نشان دهید، شاید بخواهید نماد آن را تغییر دهید. برای اطلاعات بیشتر، به اجازه دادن به برنامه‌های دیگر برای شروع فعالیت شما مراجعه کنید.

اجازه‌ها

برنامه‌های Android باید برای دسترسی به داده‌های حساس کاربر، مثل مخاطبین و پیامک، یا برخی‌از ویژگی‌های سیستم، مثل دوربین و دسترسی به اینترنت، اجازه درخواست کنند. هر اجازه با برچسبی یکتا مشخص می‌شود. برای مثال، برنامه‌ای که باید پیامک ارسال کند باید خط زیر را در مانیفست داشته باشد:

<manifest ... >
    <uses-permission android:name="android.permission.SEND_SMS"/>
    ...
</manifest>

از Android 6.0 (سطح میانای برنامه‌سازی کاربردی ۲۳) به بعد، کاربر می‌تواند برخی‌از اجازه‌های برنامه را در زمان اجرا تأیید یا رد کند. اما صرف‌نظر از اینکه برنامه‌تان از کدام نسخه Android پشتیبانی می‌کند، باید همه درخواست‌های اجازه را با عنصر <uses-permission> در مانیفست اعلام کنید. اگر اجازه اعطا شود، برنامه می‌تواند از ویژگی‌های محافظت‌شده استفاده کند. اگر این‌طور نباشد، تلاش‌های آن برای دسترسی به این ویژگی‌ها ناموفق خواهد بود.

برنامه شما همچنین می‌تواند از مؤلفه‌های خودش با اجازه‌ها محافظت کند. این برنامه می‌تواند از هرکدام از اجازه‌هایی که Android تعریف کرده است (همان‌طور که در android.Manifest.permission فهرست شده است) یا اجازه‌ای که در برنامه دیگری اعلام شده است استفاده کند. برنامه شما همچنین می‌تواند اجازه‌های خودش را تعریف کند. اجازه جدیدی با عنصر <permission> اعلام شده است.

برای اطلاعات بیشتر، به اجازه‌ها در Android مراجعه کنید.

سازگاری دستگاه

فایل مانیفست همچنین جایی است که می‌توانید اعلام کنید برنامه‌تان به چه نوع ویژگی‌های سخت‌افزاری یا نرم‌افزاری نیاز دارد و درنتیجه برنامه‌تان با چه نوع دستگاه‌هایی سازگار است. «فروشگاه Google Play» به کاربران اجازه نمی‌دهد برنامه‌تان را در دستگاه‌هایی نصب کنند که ویژگی‌ها یا نسخه سیستم موردنیاز برنامه‌تان را ارائه نمی‌دهند.

چند برچسب مانیفست وجود دارد که مشخص می‌کند برنامه‌تان با کدام دستگاه‌ها سازگار است. موارد زیر از رایج‌ترین آن‌ها هستند.

<uses-feature>

عنصر <uses-feature> به شما امکان می‌دهد ویژگی‌های سخت‌افزاری و نرم‌افزاری موردنیاز برنامه‌تان را اعلام کنید. برای مثال، اگر برنامه‌تان نمی‌تواند عملکرد اصلی را در دستگاهی بدون حسگر قطب‌نما ارائه دهد، می‌توانید حسگر قطب‌نما را با برچسب مانیفست زیر به‌عنوان الزامی اعلام کنید:

<manifest ... >
    <uses-feature android:name="android.hardware.sensor.compass"
                  android:required="true" />
    ...
</manifest>

توجه: اگر می‌خواهید برنامه‌تان را در Chromebook دردسترس قرار دهید، محدودیت‌های مهمی در ویژگی‌های سخت‌افزاری و نرم‌افزاری وجود دارد که باید درنظر بگیرید. برای اطلاعات بیشتر، به سازگاری مانیفست برنامه برای Chromebook مراجعه کنید.

<uses-sdk>

هر نسخه پلاتفرم بعدی اغلب میاناهای برنامه‌سازی کاربردی جدیدی اضافه می‌کند که در نسخه قبلی دردسترس نیستند. برای نشان دادن حداقل نسخه‌ای که برنامه‌تان با آن سازگار است، مانیفست شما باید شامل برچسب <uses-sdk> و مشخصه minSdkVersion آن باشد.

بااین‌حال، توجه داشته باشید که مشخصه‌های عنصر <uses-sdk> با ویژگی‌های متناظر در فایل build.gradle لغو می‌شوند. بنابراین، اگر از Android Studio استفاده می‌کنید، مقادیر minSdkVersion و targetSdkVersion را در آنجا مشخص کنید:

android {
    defaultConfig {
        applicationId 'com.example.myapp'

        // Defines the minimum API level required to run the app.
        minSdkVersion 23

        // Specifies the API level used to test the app.
        targetSdkVersion 36
        ...
    }
}

android {
    defaultConfig {
        applicationId = "com.example.myapp"

        // Defines the minimum API level required to run the app.
        minSdkVersion(23)

        // Specifies the API level used to test the app.
        targetSdkVersion(36)
        ...
    }
}

برای اطلاعات بیشتر درباره فایل build.gradle، درباره نحوه پیکربندی ساخت بخوانید.

برای کسب اطلاعات بیشتر درباره نحوه اعلام پشتیبانی برنامه‌تان از دستگاه‌های مختلف، نمای کلی سازگاری دستگاه را ببینید.

قراردادهای فایل

این بخش قراردادها و قوانینی را شرح می‌دهد که معمولاً برای همه عناصر و مشخصه‌ها در فایل مانیفست اعمال می‌شود.

عناصر

فقط عناصر <manifest> و <application> موردنیاز است. هرکدام باید فقط یک‌بار رخ دهد. اکثر عناصر دیگر می‌توانند صفر یا چند بار رخ دهند. بااین‌حال، برخی‌از آن‌ها باید وجود داشته باشند تا فایل مانیفست مفید باشد.

همه مقادیر ازطریق مشخصه‌ها تنظیم می‌شوند، نه به‌عنوان داده‌های نویسه‌ای در یک عنصر.

عناصر در یک سطح معمولاً مرتب نمی‌شوند. برای مثال، عناصر <activity>، <provider>، و <service> را می‌توان با هر ترتیبی قرار داد. دو استثنای کلیدی برای این قانون وجود دارد:

• عنصر <activity-alias> باید از <activity> که نام مستعار آن است پیروی کند.
• عنصر <application> باید آخرین عنصر داخل عنصر <manifest> باشد.

مشخصه‌ها

ازنظر فنی، همه مشخصه‌ها اختیاری هستند. بااین‌حال، بسیاری از مشخصه‌ها باید مشخص شوند تا عنصر بتواند به هدف خود برسد. برای مشخصه‌های واقعاً اختیاری، اسناد مرجع مقادیر پیش‌فرض را نشان می‌دهد.

به‌جز برخی‌از مشخصه‌های عنصر ریشه <manifest> ، همه نام‌های مشخصه با پیشوند android: شروع می‌شوند، مانند android:alwaysRetainTaskState. چون پیشوند جهانی است، سند معمولاً هنگام ارجاع به مشخصه‌ها با نام، آن را حذف می‌کند.

چندین مقدار

اگر بیش‌از یک مقدار را بتوان مشخص کرد، عنصر تقریباً همیشه تکرار می‌شود، به‌جای اینکه چندین مقدار در یک عنصر فهرست شود. برای مثال، فیلتر قصد می‌تواند چندین کنش را فهرست کند:

<intent-filter ... >
    <action android:name="android.intent.action.EDIT" />
    <action android:name="android.intent.action.INSERT" />
    <action android:name="android.intent.action.DELETE" />
    ...
</intent-filter>

مقادیر منبع

برخی‌از مشخصه‌ها مقادیری دارند که به کاربران نمایش داده می‌شود، مثل عنوان فعالیت یا نماد برنامه شما. مقدار این مشخصه‌ها ممکن است براساس زبان کاربر یا پیکربندی‌های دیگر دستگاه متفاوت باشد (مثلاً برای ارائه اندازه نماد متفاوت براساس تراکم پیکسل دستگاه)، بنابراین مقادیر باید از منبع یا زمینه‌ای تنظیم شوند، به‌جای اینکه در فایل مانیفست کدنویسی ثابت شوند. سپس مقدار واقعی می‌تواند براساس منابع جایگزینی که برای پیکربندی‌های مختلف دستگاه ارائه می‌دهید تغییر کند.

منابع به‌صورت مقادیری با قالب زیر بیان می‌شوند:

"@[package:]type/name"

اگر منبع توسط برنامه‌تان ارائه شده باشد، می‌توانید نام package را حذف کنید (ازجمله اگر توسط وابستگی کتابخانه ارائه شده باشد، زیرا منابع کتابخانه در منابع شما ادغام می‌شوند). تنها نام بسته معتبر دیگر android است، وقتی می‌خواهید از منبعی از چارچوب Android استفاده کنید.

‫type نوعی منبع است، مثل string یا drawable، و name نامی است که منبع خاص را شناسایی می‌کند. به‌عنوان مثال:

<activity android:icon="@drawable/smallPic" ... >

برای اطلاعات بیشتر درباره نحوه افزودن منابع به پروژه، نمای کلی منابع برنامه را بخوانید.

برای اعمال مقداری که در زمینه تعریف شده است، اولین نویسه باید به‌جای @، ? باشد:

"?[package:]type/name"

مقادیر رشته

وقتی مقدار مشخصه رشته است، از واکج‌خط دوگانه (\\) برای نویسه‌های گریز استفاده کنید، مثلاً \\n برای خط جدید یا \\uxxxx برای نویسه یونی‌کد.

مرجع عناصر مانیفست

جدول زیر پیوندهایی به اسناد مرجع برای همه عناصر معتبر در فایل AndroidManifest.xml ارائه می‌دهد.

محدودیت‌ها

برچسب‌های زیر ازنظر تعداد دفعات تکرار در فایل مانیفست محدودیت دارند:

مشخصه‌های زیر برای حداکثر طولشان محدودیت دارند:

نمونه فایل مانیفست

XML زیر نمونه ساده‌ای AndroidManifest.xml است که دو فعالیت را برای برنامه اعلام می‌کند.

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:versionCode="1"
    android:versionName="1.0">

    <!-- Beware that these values are overridden by the build.gradle file -->
    <uses-sdk android:minSdkVersion="15" android:targetSdkVersion="26" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <!-- This name is resolved to com.example.myapp.MainActivity
             based on the namespace property in the build.gradle file -->
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <activity
            android:name=".DisplayMessageActivity"
            android:parentActivityName=".MainActivity" />
    </application>
</manifest>