סקירה כללית של קובץ המניפסט של האפליקציה

לכל פרויקט אפליקציה צריך להיות קובץ AndroidManifest.xml, עם השם הזה בדיוק, בבסיס של מקור הפרויקט. קובץ המניפסט מתאר מידע חיוני על האפליקציה שלכם לכלי הבנייה של Android, למערכת ההפעלה Android ול-Google Play.

בין היתר, קובץ המניפסט נדרש כדי להצהיר על הדברים הבאים:

• הרכיבים של האפליקציה, כולל כל הפעילויות, השירותים, מקלטי השידור וספקי התוכן. כל רכיב חייב להגדיר מאפיינים בסיסיים, כמו השם של מחלקת Kotlin או Java שלו. הוא יכול גם להצהיר על יכולות, כמו הגדרות המכשיר שהוא יכול לטפל בהן, ועל מסנני כוונות שמתארים איך אפשר להפעיל את הרכיב. מידע נוסף על רכיבי אפליקציות זמין בקטע הבא.
• ההרשאות שהאפליקציה צריכה כדי לגשת לחלקים מוגנים במערכת או לאפליקציות אחרות. בנוסף, מוצהרות בו כל ההרשאות שאפליקציות אחרות צריכות לקבל כדי לגשת לתוכן מהאפליקציה הזו. מידע נוסף על הרשאות מופיע בקטע הבא.
• תכונות החומרה והתוכנה שהאפליקציה דורשת, שמשפיעות על המכשירים שבהם אפשר להתקין את האפליקציה מ-Google Play. מידע נוסף על תאימות המכשיר

אם אתם משתמשים ב-Android Studio כדי ליצור את האפליקציה, קובץ המניפסט נוצר בשבילכם, ורוב רכיבי המניפסט החיוניים מתווספים בזמן שאתם יוצרים את האפליקציה, במיוחד כשאתם משתמשים בתבניות קוד.

תכונות הקובץ

בקטעים הבאים מוסבר איך חלק מהמאפיינים החשובים ביותר של האפליקציה משתקפים בקובץ המניפסט.

רכיבי אפליקציה

לכל רכיב אפליקציה שיוצרים באפליקציה, צריך להצהיר על רכיב 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 על סמך הצהרות של מסנן Intent בקובץ המניפסט של כל אפליקציה. המערכת מפעילה מופע של הרכיב התואם ומעבירה את האובייקט Intent לרכיב הזה. אם יותר מאפליקציה אחת יכולה לטפל בכוונת המשתמש, הוא יכול לבחור באיזו אפליקציה להשתמש.

רכיב של אפליקציה יכול להכיל כל מספר של מסנני Intent (מוגדרים באמצעות הרכיב <intent-filter>), כשכל אחד מהם מתאר יכולת שונה של הרכיב הזה.

מידע נוסף זמין במאמר Intents and Intent Filters.

סמלים ותוויות

למספר רכיבי מניפסט יש מאפיינים icon ו-label להצגת סמל קטן ותווית טקסט, בהתאמה, למשתמשים עבור רכיב האפליקציה המתאים.

בכל מקרה, הסמל והתווית שמוגדרים ברכיב אב הופכים לערך ברירת המחדל icon ו-label של כל רכיבי הבן. לדוגמה, הסמל והתווית שמוגדרים ברכיב <application> הם סמל ברירת המחדל והתווית של כל אחד מהרכיבים של האפליקציה, כמו כל הפעילויות.

הסמל והתווית שמוגדרים ב-<intent-filter> של רכיב מוצגים למשתמש בכל פעם שהרכיב הזה מוצג כאפשרות למימוש כוונה. כברירת מחדל, הסמל הזה עובר בירושה מהסמל שמוגדר לרכיב האב, כלומר מהרכיב <activity> או <application>.

יכול להיות שתרצו לשנות את הסמל של מסנן Intent אם הוא מספק פעולה ייחודית שתרצו לציין בצורה טובה יותר בתיבת הדו-שיח לבחירת אפליקציה. מידע נוסף זמין במאמר בנושא איך מאפשרים לאפליקציות אחרות להתחיל את הפעילות שלכם.

הרשאות

אפליקציות ל-Android חייבות לבקש הרשאה לגשת לנתונים אישיים רגישים של משתמשים, כמו אנשי קשר ו-SMS, או לתכונות מסוימות של המערכת, כמו המצלמה וגישה לאינטרנט. כל הרשאה מזוהה באמצעות תווית ייחודית. לדוגמה, אפליקציה שצריכה לשלוח הודעות SMS חייבת לכלול את השורה הבאה במניפסט:

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

החל מ-Android 6.0 (רמת API‏ 23), המשתמש יכול לאשר או לדחות חלק מההרשאות של האפליקציה בזמן הריצה. אבל לא משנה איזו גרסת 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>

בכל גרסה עוקבת של הפלטפורמה נוספים בדרך כלל ממשקי API חדשים שלא זמינים בגרסה הקודמת. כדי לציין את הגרסה המינימלית שאיתה האפליקציה תואמת, צריך לכלול במניפסט את התג <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 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 זמין במאמר איך מגדירים את הגרסה.

מידע נוסף על הצהרה על תמיכה במכשירים שונים באפליקציה זמין במאמר סקירה כללית על תאימות מכשירים.

מוסכמות לגבי קבצים

בקטע הזה מתוארים המוסכמות והכללים שחלים בדרך כלל על כל הרכיבים והמאפיינים בקובץ המניפסט.

רכיבים

נדרשים רק הרכיבים <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 framework.

‫type הוא סוג המשאב, כמו string או drawable, ו-name הוא השם שמזהה את המשאב הספציפי. לדוגמה:

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

מידע נוסף על הוספת משאבים לפרויקט זמין במאמר סקירה כללית על משאבי אפליקציות.

כדי להחיל במקום זאת ערך שמוגדר בעיצוב, התו הראשון צריך להיות ? במקום @:

"?[package:]type/name"

ערכי מחרוזת

אם ערך המאפיין הוא מחרוזת, צריך להשתמש בלוכסנים כפולים (\\) כדי לבצע escape לתווים, כמו \\n למעבר לשורה חדשה או \\uxxxx לתו Unicode.

הפניה לרכיבי מניפסט

בטבלה הבאה מופיעים קישורים למסמכי העזר של כל הרכיבים התקינים בקובץ 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>