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

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

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

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

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

תכונות קבצים

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

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

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

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

מציינים את השם של מחלקת המשנה באמצעות השדה 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-filter>), כאשר כל אחד מהם מתאר יכולת אחרת של הרכיב.

מידע נוסף זמין במסמך מנגנוני Intent ומסנני Intent.

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

למספר אלמנטים במניפסט יש מאפיינים 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>

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

<uses-sdk>

כל גרסת פלטפורמה רציפה מוסיפה לעיתים קרובות ממשקי API חדשים שלא זמינה בגרסה הקודמת. כדי לציין את הגרסה המינימלית שאיתה האפליקציה תואמת, המניפסט צריך לכלול את התג <uses-sdk> ואת המאפיין minSdkVersion שלו.

עם זאת, חשוב לזכור שהמאפיינים ברכיב <uses-sdk> מוחרגים על ידי המאפיינים התואמים בקובץ build.gradle. לכן, אם אתם משתמשים ב-Android Studio, צריך לציין את minSdkVersion ואת targetSdkVersion ערכים במקום זאת:

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

כל הערכים מוגדרים באמצעות מאפיינים, ולא כנתוני תווים בתוך אלמנט.

בדרך כלל, רכיבים באותה רמה לא מסודרים. לדוגמה, <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, אם רוצים להשתמש במשאב מהמסגרת של Android.

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

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

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

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

"?[package:]type/name"

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

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

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

<action> הוספת פעולה למסנן Intent.
<activity> הכרזה על רכיב פעילות.
<activity-alias> מצהיר על כינוי של פעילות.
<application> מצהירה על הבקשה.
<category> הוספת שם קטגוריה למסנן Intent.
<compatible-screens> מציינת כל אחת מההגדרות של המסך שהאפליקציה תואמת לה.
<data> הוספת מפרט נתונים למסנן Intent.
<grant-uri-permission> מציינת את קבוצות המשנה של נתוני האפליקציה שלספק התוכן הראשי יש הרשאה לגשת אליהם.
<instrumentation> מצהירה על מחלקה Instrumentation שמאפשרת לעקוב אחר האינטראקציה של אפליקציה עם המערכת.
<intent-filter> מציינת את סוגי הכוונות שפעילות, שירות או מקלט שידורים יכולים להגיב להן.
<manifest> רכיב הבסיס של קובץ AndroidManifest.xml.
<meta-data> צמד של שם-ערך לפריט של נתונים שרירותיים נוספים, שניתן לספק לרכיב ההורה.
<path-permission> הגדרת הנתיב וההרשאות הנדרשות לקבוצת משנה ספציפית של נתונים בתוך ספק תוכן.
<permission> הצהרה על הרשאת אבטחה שאפשר להשתמש בה כדי להגביל את הגישה לרכיבים או לתכונות ספציפיים של האפליקציה הזו או של אפליקציות אחרות.
<permission-group> הצהרת שם על קיבוץ לוגי של הרשאות קשורות.
<permission-tree> מצהיר על שם הבסיס של עץ הרשאות.
<provider> מצהיר על רכיב של ספק תוכן.
<queries> מצהירה על קבוצת האפליקציות האחרות שהאפליקציה מתכוונת לגשת אליהן. מידע נוסף במדריך על חשיפה של חבילות סינון.
<receiver> הכרזה על רכיב של מקלט שידורים.
<service> הצהרה על רכיב שירות.
<supports-gl-texture> הצהרה על פורמט דחיסה יחיד של טקסטורת GL שתומכת בו האפליקציה.
<supports-screens> הכלי מכריז על גודלי המסך שנתמכים באפליקציה ומפעיל את מצב תאימות המסך במסכים גדולים יותר מאלה שנתמכים באפליקציה.
<uses-configuration> מציין תכונות קלט ספציפיות שנדרשות לאפליקציה.
<uses-feature> הצהרה על תכונה אחת של חומרה או תוכנה שבה האפליקציה משתמשת.
<uses-library> מציינת ספרייה משותפת שאליה צריך לקשר את האפליקציה.
<uses-native-library> מציין ספרייה משותפת מקורית שסופקה על ידי הספק, שאליה צריך לקשר את האפליקציה.
<uses-permission> מציינת הרשאת מערכת שהמשתמש צריך להעניק כדי שהאפליקציה תפעל בצורה תקינה.
<uses-permission-sdk-23> מציין שאפליקציה רוצה לקבל הרשאה מסוימת, אבל רק אם האפליקציה מותקנת במכשיר עם Android מגרסה 6.0 (רמת API ‏23) ואילך.
<uses-sdk> מאפשרת לציין את התאימות של אפליקציה לגרסה אחת או יותר של פלטפורמת Android באמצעות מספר שלם ברמת ה-API.

המגבלות

למספר ההופעות של התגים הבאים בקובץ מניפסט יש מגבלה:

שם התג הגבלה
<package> 1000
<meta-data> 1000
<uses-library> 1000

במאפיינים הבאים יש מגבלה על האורך המקסימלי שלהם:

מאפיין הגבלה
name 1024
versionName 1024
host 255
mimeType 255

קובץ מניפסט לדוגמה

קובץ ה-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>