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

לכל פרויקט אפליקציה צריך להיות קובץ 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-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 זמין במאמר איך מגדירים את ה-build.

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

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

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

רכיבים

חובה להשתמש רק ברכיבים <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>