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

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

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

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

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

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

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

اجزای برنامه

برای هر کامپوننت برنامه که در برنامه خود ایجاد می‌کنید، یک عنصر 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 تعریف می‌شود و عملی را که باید انجام شود، توصیف می‌کند، از جمله داده‌هایی که باید روی آنها عمل شود، دسته کامپوننتی که انتظار می‌رود عمل را انجام دهد و سایر دستورالعمل‌ها.

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

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

برای اطلاعات بیشتر، به سند Intents و Intent Filters مراجعه کنید.

آیکون‌ها و برچسب‌ها

تعدادی از عناصر مانیفست دارای ویژگی‌های icon و label هستند که به ترتیب یک آیکون کوچک و یک برچسب متنی را برای کاربران مربوط به کامپوننت برنامه مربوطه نمایش می‌دهند.

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

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

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

مجوزها

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

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

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

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

برای اطلاعات بیشتر، به بخش «مجوزها در اندروید» مراجعه کنید.

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

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

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

<uses-feature>

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

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

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

<uses-sdk>

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

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

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

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

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

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

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

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

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

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

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

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

عناصر

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

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

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

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

ویژگی‌ها

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

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

مقادیر چندگانه

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

<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 است، زمانی که می‌خواهید از منبعی از چارچوب اندروید استفاده کنید.

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

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

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

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

"?[ package :] type / name "

مقادیر رشته‌ای

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

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

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

محدودیت‌ها

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

ویژگی‌های زیر محدودیتی در حداکثر طول خود دارند:

مثال فایل مانیفست

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

<?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>