שירותים שפועלים בחזית

שירותים שפועלים בחזית מבצעים פעולות שהמשתמשים רואים.

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

דוגמאות לאפליקציות שמשתמשות בשירותים שפועלים בחזית:

• אפליקציית נגן מוזיקה שמפעילה מוזיקה בשירות שפועל בחזית. יכול להיות שההתראה תציג את השיר הנוכחי שמושמע.
• אפליקציית כושר שמתעדת ריצה של משתמש בשירות שפועל בחזית, אחרי שקיבלה הרשאה מהמשתמש. יכול להיות שההתראה תציג את המרחק שהמשתמש עבר במהלך סשן הכושר הנוכחי.

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

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

המשתמש יכול לסגור את ההתראה כברירת מחדל

החל מ-Android 13 (רמת API 33), המשתמשים יכולים לסגור את ההתראה המשויכת לשירות שפועל בחזית כברירת מחדל. כדי לעשות זאת, המשתמשים מבצעים מחווה של החלקה על ההתראה. בדרך כלל, ההתראה לא תיסגר אלא אם השירות שפועל בחזית יופסק או יוסר ממנה.

אם אתם לא רוצים שהמשתמש יוכל לסגור את ההתראה, עליכם להעביר את הערך true ל-method‏ setOngoing() כשיוצרים את ההתראה באמצעות Notification.Builder.

שירותים שמציגים התראה באופן מיידי

אם לשירות בחזית יש לפחות אחת מהמאפיינים הבאים, המערכת תציג את ההתראה המשויכת מיד אחרי שהשירות יתחיל לפעול, גם במכשירים עם Android מגרסה 12 ואילך:

• השירות משויך להתראה שכוללת לחצני פעולה.
• לשירות יש foregroundServiceType של mediaPlayback,‏ mediaProjection או phoneCall.
• השירות מספק תרחיש לדוגמה שקשור לשיחות טלפון, לניווט או להפעלת מדיה, כפי שמוגדר במאפיין הקטגוריה של ההתראה.
• השירות ביקש שלא לשנות את ההתנהגות על ידי העברת הערך FOREGROUND_SERVICE_IMMEDIATE אל setForegroundServiceBehavior() בזמן הגדרת ההתראה.

ב-Android 13 ואילך (רמת API 33 ואילך), אם המשתמש דוחה את הרשאת ההתראות, הוא עדיין רואה התראות שקשורות לשירותים שפועלים בחזית במנהל המשימות, אבל לא רואה אותן בחלונית ההתראות.

הצהרה על שירותים שפועלים בחזית במניפסט

במניפסט של האפליקציה, מגדירים כל אחד מהשירותים של האפליקציה שפועלים בחזית באמצעות רכיב <service>. לכל שירות, משתמשים במאפיין android:foregroundServiceType כדי להצהיר על סוג העבודה שהשירות מבצע.

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

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>
  <application ...>

    <service
        android:name=".MyMediaPlaybackService"
        android:foregroundServiceType="mediaPlayback"
        android:exported="false">
    </service>
  </application>
</manifest>

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

android:foregroundServiceType="camera|microphone"

שליחת בקשה להרשאות לשימוש בשירות שפועל בחזית

אפליקציות שמטרגטות ל-Android 9 (רמת API 28) ואילך ומשתמשות בשירותים שפועלים בחזית צריכות לבקש את ההרשאה FOREGROUND_SERVICE במניפסט של האפליקציה, כפי שמתואר בקטע הקוד הבא. זוהי הרשאה רגילה, ולכן המערכת מעניקה אותה באופן אוטומטי לאפליקציה המבקשת.

בנוסף, אם האפליקציה מטרגטת לרמת API 34 ומעלה, היא צריכה לבקש את סוג ההרשאה המתאים לסוג העבודה שהשירות שפועל בחזית יבצע. לכל סוג של שירות שפועל בחזית יש סוג הרשאה תואם. לדוגמה, אם אפליקציה מפעילה שירות שפועל בחזית שמשתמש במצלמה, צריך לבקש את ההרשאות FOREGROUND_SERVICE ו-FOREGROUND_SERVICE_CAMERA. אלה כולן הרשאות רגילות, ולכן המערכת מעניקה אותן באופן אוטומטי אם הן מפורטות במניפסט.

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>

    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA"/>

    <application ...>
        ...
    </application>
</manifest>

תנאים מוקדמים לשימוש בשירות שפועל בחזית

החל מ-Android 14 (רמת API 34), כשמפעילים שירות שפועל בחזית, המערכת בודקת אם מתקיימים תנאים מוקדמים ספציפיים בהתאם לסוג השירות. לדוגמה, אם מנסים להפעיל שירות שפועל בחזית מסוג location, המערכת בודקת אם לאפליקציה כבר יש את ההרשאה ACCESS_COARSE_LOCATION או ACCESS_FINE_LOCATION. אם לא, המערכת תשליך את השגיאה SecurityException.

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

הפעלת שירות שפועל בחזית

לפני שמבקשים מהמערכת להפעיל שירות כשירות שפועל בחזית, צריך להפעיל את השירות עצמו:

val intent = Intent(...) // Build the intent for the service
context.startForegroundService(intent)

Context context = getApplicationContext();
Intent intent = new Intent(...); // Build the intent for the service
context.startForegroundService(intent);

בתוך השירות, בדרך כלל ב-onStartCommand(), אפשר לבקש שהשירות יפעל בחזית. כדי לעשות זאת, צריך להפעיל את ServiceCompat.startForeground() (האפשרות הזו זמינה ב-androidx-core מגרסה 1.12 ואילך). השיטה מקבלת את הפרמטרים הבאים:

• השירות
• מספר שלם חיובי שמזהה באופן ייחודי את ההתראה בשורת הסטטוס
• האובייקט Notification עצמו
• סוגי השירותים שפועלים בחזית שמזהים את העבודה שהשירות מבצע

הסוגים האלה עשויים להיות קבוצת משנה של הסוגים שמוצהרים במניפסט, בהתאם לתרחיש לדוגמה הספציפי. לאחר מכן, אם צריך להוסיף עוד סוגי שירותים, אפשר לבצע שוב קריאה ל-startForeground().

לדוגמה, נניח שאפליקציית כושר מפעילה שירות למעקב אחר ריצה שתמיד צריך להשתמש בו כדי לקבל מידע על location, אבל יכול להיות שלא תצטרכו להפעיל מדיה. תצטרכו להצהיר על location ועל mediaPlayback במניפסט. אם משתמש מתחיל ריצה ורק רוצה שיבוצע מעקב אחרי המיקום שלו, האפליקציה צריכה לבצע קריאה ל-startForeground() ולהעביר רק את ההרשאה ACCESS_FINE_LOCATION. לאחר מכן, אם המשתמש רוצה להתחיל להפעיל אודיו, צריך לקרוא שוב ל-startForeground() ולהעביר את השילוב הבינארי של כל סוגי השירותים שפועלים בחזית (במקרה הזה, ACCESS_FINE_LOCATION|FOREGROUND_SERVICE_MEDIA_PLAYBACK).

דוגמה להפעלה של שירות שפועל בחזית של המצלמה:

class MyCameraService: Service() {

  private fun startForeground() {
    // Before starting the service as foreground check that the app has the
    // appropriate runtime permissions. In this case, verify that the user has
    // granted the CAMERA permission.
    val cameraPermission =
            PermissionChecker.checkSelfPermission(this, Manifest.permission.CAMERA)
    if (cameraPermission != PermissionChecker.PERMISSION_GRANTED) {
        // Without camera permissions the service cannot run in the foreground
        // Consider informing user or updating your app UI if visible.
        stopSelf()
        return
    }

    try {
        val notification = NotificationCompat.Builder(this, "CHANNEL_ID")
            // Create the notification to display while the service is running
            .build()
        ServiceCompat.startForeground(
            /* service = */ this,
            /* id = */ 100, // Cannot be 0
            /* notification = */ notification,
            /* foregroundServiceType = */
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA
            } else {
                0
            },
        )
    } catch (e: Exception) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
                && e is ForegroundServiceStartNotAllowedException) {
            // App not in a valid state to start foreground service
            // (e.g. started from bg)
        }
        // ...
    }
  }
}

public class MyCameraService extends Service {

    private void startForeground() {
        // Before starting the service as foreground check that the app has the
        // appropriate runtime permissions. In this case, verify that the user
        // has granted the CAMERA permission.
        int cameraPermission =
            ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA);
        if (cameraPermission == PackageManager.PERMISSION_DENIED) {
            // Without camera permissions the service cannot run in the
            // foreground. Consider informing user or updating your app UI if
            // visible.
            stopSelf();
            return;
        }

        try {
            Notification notification =
                new NotificationCompat.Builder(this, "CHANNEL_ID")
                    // Create the notification to display while the service
                    // is running
                    .build();
            int type = 0;
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                type = ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA;
            }
            ServiceCompat.startForeground(
                    /* service = */ this,
                    /* id = */ 100, // Cannot be 0
                    /* notification = */ notification,
                    /* foregroundServiceType = */ type
            );
        } catch (Exception e) {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S &&
                    e instanceof ForegroundServiceStartNotAllowedException
            ) {
                // App not in a valid state to start foreground service
                // (e.g started from bg)
            }
            // ...
        }
    }

    //...
}

הסרת שירות מחזית המסך

כדי להסיר את השירות מחזית המסך, צריך להפעיל את הפונקציה stopForeground(). השיטה מקבלת ערך בוליאני שמציין אם להסיר גם את ההתראה בסרגל הסטטוס. חשוב לציין שהשירות ממשיך לפעול.

אם תפסיקו את השירות בזמן שהוא פועל בחזית, ההתראה שלו תוסר.

טיפול בהפסקה של אפליקציות שפועלות בשירותים שפועלים בחזית ביוזמת המשתמש

החל מ-Android 13 (רמת API 33), משתמשים יכולים להשלים תהליך עבודה ממסגרת ההתראות כדי להפסיק אפליקציה עם שירותים שפועלים בחזית, ללא קשר לגרסה של ה-SDK לטירגוט של האפליקציה. האפשרות הזו, שנקראת מנהל המשימות, מציגה רשימה של אפליקציות שפועל בהן כרגע שירות בחזית.

הרשימה הזו מסומנת בתווית אפליקציות פעילות. לצד כל אפליקציה מופיע לחצן עצירה. באיור 1 מוצג תהליך העבודה של מנהל המשימות במכשיר עם Android 13.

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

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

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

adb shell cmd activity stop-app PACKAGE_NAME

פטורים

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

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

פטורים מהצגה בכלל במנהל המשימות

האפליקציות הבאות יכולות להפעיל שירות בחזית ולא להופיע בכלל במנהל המשימות:

• אפליקציות ברמת המערכת
• אפליקציות בטיחות, כלומר אפליקציות עם התפקיד ROLE_EMERGENCY
• מכשירים שנמצאים במצב הדגמה

החרגות מאפשרות של משתמשים לעצור את ההפעלה

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

• אפליקציות של בעלי המכשיר
• אפליקציות של בעלי הפרופיל
• אפליקציות קבועות
• אפליקציות עם התפקיד ROLE_DIALER

בתרחישים רבים של שימוש, יש ממשקי API של פלטפורמה או של Jetpack שאפשר להשתמש בהם כדי לבצע משימות שבדרך כלל מבוצעות על ידי שירות בחזית. אם יש ממשק API מתאים שנועד למטרה מסוימת, כמעט תמיד כדאי להשתמש בו במקום בשירות שפועל בחזית. ממשקי API ייעודיים מספקים לרוב יכולות נוספות ספציפיות לתרחיש לדוגמה, שאחרת תצטרכו לפתח בעצמכם. לדוגמה, Bubbles API מטפל בלוגיקה המורכבת של ממשק המשתמש באפליקציות שליחת הודעות שצריכות להטמיע תכונות של בועות צ'אט.

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

הגבלות על הפעלה של שירות שפועל בחזית מהרקע

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

בנוסף, אם אפליקציה רוצה להפעיל שירות שפועל בחזית שדורש הרשאות while-in-use (לדוגמה, חיישן גוף, מצלמה, מיקום או מיקרופון), היא לא יכולה ליצור את השירות בזמן שהאפליקציה פועלת ברקע, גם אם האפליקציה נכללת באחת מההחרגות מההגבלות על הפעלה ברקע. הסיבה לכך מוסברת בקטע הגבלות על הפעלת שירותים בחזית שצריכים הרשאות לשימוש.

החרגות מהגבלות על הפעלה מהרקע

במצבים הבאים, האפליקציה יכולה להפעיל שירותים שפועלים בחזית גם כשהיא פועלת ברקע:

• האפליקציה עוברת ממצב שגלוי למשתמשים, כמו פעילות.
• האפליקציה יכולה להפעיל פעילות מהרקע, מלבד במקרה שיש לאפליקציה פעילות בערימה האחורית של משימה קיימת.

• האפליקציה מקבלת הודעה בעדיפות גבוהה באמצעות Firebase Cloud Messaging.

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

• האפליקציה מפעילה התראה מדויקת כדי להשלים פעולה שהמשתמש מבקש.

• האפליקציה היא שיטת הקלט הנוכחית של המכשיר.

• האפליקציה מקבלת אירוע שקשור לגיאו-פיינס או למעבר של זיהוי פעילות.

• אחרי שהמכשיר יופעל מחדש ויקבל את פעולת הכוונה ACTION_BOOT_COMPLETED,‏ ACTION_LOCKED_BOOT_COMPLETED או ACTION_MY_PACKAGE_REPLACED במקלט שידור.

• האפליקציה מקבלת את פעולת הכוונה ACTION_TIMEZONE_CHANGED,‏ ACTION_TIME_CHANGED או ACTION_LOCALE_CHANGED במקלט שידורים.

• האפליקציה מקבלת את האירוע ACTION_TRANSACTION_DETECTED מ-NfcService.

• אפליקציות עם תפקידים או הרשאות מסוימים במערכת, כמו בעלי המכשיר ובעלי הפרופיל.

• האפליקציה שלכם משתמשת ב-Companion Device Manager ומצהירה על ההרשאה REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND או על ההרשאה REQUEST_COMPANION_RUN_IN_BACKGROUND. כשאפשר, כדאי להשתמש ב-REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND.

• המשתמש משבית את האופטימיזציות של הסוללה באפליקציה.

• לאפליקציה יש את ההרשאה SYSTEM_ALERT_WINDOW. הערה: אם האפליקציה שלכם מטרגטת את Android 15 ואילך, היא חייבת לקבל את ההרשאה SYSTEM_ALERT_WINDOW ו חייבת להיות לה כרגע חלון שכבת-על גלוי.

הגבלות על הפעלת שירותים שפועלים בחזית שצריכים הרשאות לשימוש בזמן אמת

ב-Android 14 (רמת API 34) ואילך, יש מצבים מיוחדים שצריך להיות מודעים אליהם כשמפעילים שירות שפועל בחזית שדורש הרשאות לשימוש פעיל.

אם האפליקציה שלכם מטרגטת את Android 14 ואילך, מערכת ההפעלה בודקת בזמן יצירת השירות שפועל בחזית כדי לוודא שלאפליקציה יש את כל ההרשאות המתאימות לסוג השירות הזה. לדוגמה, כשיוצרים שירות שפועל בחזית מסוג microphone, מערכת ההפעלה מוודאת שלאפליקציה יש כרגע את ההרשאה RECORD_AUDIO. אם אין לכם את ההרשאה הזו, המערכת תשליך את השגיאה SecurityException.

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

באופן דומה, אם האפליקציה פועלת ברקע ויוצרת שירות בריאות שדורש את ההרשאה BODY_SENSORS, לאפליקציה אין כרגע את ההרשאה הזו והמערכת תיצור חריגה. (הכלל הזה לא חל אם מדובר בשירות בריאות שדורש הרשאות שונות, כמו ACTIVITY_RECOGNITION). קריאה ל-PermissionChecker.checkSelfPermission() לא מונעת את הבעיה הזו. אם לאפליקציה יש הרשאה לשימוש בזמן השימוש, והיא קוראת ל-checkSelfPermission() כדי לבדוק אם יש לה את ההרשאה הזו, ה-method מחזיר את הערך PERMISSION_GRANTED גם אם האפליקציה פועלת ברקע. כשהשיטה מחזירה את הערך PERMISSION_GRANTED, המשמעות היא "האפליקציה שלך קיבלה את ההרשאה הזו בזמן שהאפליקציה בשימוש".

לכן, אם לשירות בחזית נדרשת הרשאה לשימוש פעיל, צריך להפעיל את Context.startForegroundService() או Context.bindService() בזמן שהאפליקציה מציגה פעילות גלויה, אלא אם השירות עומד באחד מהחריגים המוגדרים.

במצבים מסוימים, גם אם שירות שפועל בחזית מופעל בזמן שהאפליקציה פועלת ברקע, הוא עדיין יכול לגשת למידע על המיקום, המצלמה והמיקרופון בזמן שהאפליקציה פועלת בחזית ('בזמן השימוש').

באותן סיטואציות, אם השירות מצהיר על סוג שירות שפועל בחזית של location והוא מופעל על ידי אפליקציה שיש לה את ההרשאה ACCESS_BACKGROUND_LOCATION, השירות הזה יכול לגשת לפרטי המיקום כל הזמן, גם כשהאפליקציה פועלת ברקע.

המצבים האלה מפורטים ברשימה הבאה:

• רכיב מערכת מפעיל את השירות.
• השירות מתחיל לפעול באמצעות אינטראקציה עם ווידג'טים של אפליקציות.
• השירות מתחיל לפעול דרך אינטראקציה עם התראה.
• השירות מתחיל בתור PendingIntent שנשלח מאפליקציה אחרת גלויה.
• השירות מופעל על ידי אפליקציה שהיא בקר מדיניות של מכשיר שפועלת במצב 'בעלי המכשיר'.
• השירות מופעל על ידי אפליקציה שמספקת את VoiceInteractionService.
• השירות מופעל על ידי אפליקציה עם ההרשאה המיוחדת START_ACTIVITIES_FROM_BACKGROUND.

איך בודקים אילו שירותים מושפעים מהבעיה באפליקציה

כשבודקים את האפליקציה, מפעילים את השירותים שלה שפועלים בחזית. אם לשירות שהופעל יש גישה מוגבלת למיקום, למיקרופון ולמצלמה, ההודעה הבאה תופיע ב-Logcat:

Foreground service started from background can not have \
location/camera/microphone access: service SERVICE_NAME