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

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

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

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

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

תכונות הקובץ

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

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

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

כדאי לשנות את הסמל של מסנן 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 שם במקום זאת:

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.

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

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

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

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

"?[package:]type/name"

ערכים של מחרוזות

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