שליחת בקשה להרשאות מיקום

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

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

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

סוגי הגישה למיקום

לכל הרשאה יש שילוב של המאפיינים הבאים:

• קטגוריה: המיקום בחזית או מיקום הרקע.
• דיוק: מיקום מדויק או מיקום משוער.

מיקום בחזית

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

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

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

• פעילות ששייכת לאפליקציה שלכם גלויה.

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

  בנוסף, מומלץ להצהיר על סוג השירות שפועל בחזית location, כפי שמוצג בקטע הקוד הבא. ב-Android 10 (רמת API‏ 29) ואילך, צריך להצהיר על סוג השירות הזה שפועל בחזית.

  <!-- Recommended for Android 9 (API level 28) and lower. -->
  <!-- Required for Android 10 (API level 29) and higher. -->
  <service
      android:name="MyNavigationService"
      android:foregroundServiceType="location" ... >
      <!-- Any inner elements would go here. -->
  </service>
  

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

<manifest ... >
  <!-- Always include this permission -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Include only if your app benefits from precise location access. -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

מיקום ברקע

אפליקציה דורשת גישה למיקום ברקע אם תכונה באפליקציה משתפת את המיקום באופן קבוע עם משתמשים אחרים או משתמשת ב-Geofencing API. דוגמאות לכך:

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

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

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

<manifest ... >
  <!-- Required only when requesting background location access on
       Android 10 (API level 29) and higher. -->
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
</manifest>

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

דיוק

מערכת Android תומכת ברמות הדיוק הבאות של המיקום:

משוער

מספק הערכת מיקום של מכשיר. אם אומדן המיקום הוא מ-LocationManagerService או FusedLocationProvider, האומדן יהיה מדויק בטווח של כ-3 קמ"ר (בערך 1.2 מיילים רבועים). האפליקציה יכולה לקבל מיקומים ברמת הדיוק הזו אם מגדירים את ההרשאה ACCESS_COARSE_LOCATION אבל לא את ההרשאה ACCESS_FINE_LOCATION.

מדויק

מספקת הערכת מיקום של המכשיר בצורה מדויקת ככל האפשר. אם אומדן המיקום הוא מ-LocationManagerService או FusedLocationProvider, האומדן הוא בדרך כלל בטווח של כ-50 מטר, ולפעמים הוא מדויק בטווח של כמה מטרים או יותר. האפליקציה יכולה לקבל מיקומים ברמת הדיוק הזו כשמצהירים על ההרשאה ACCESS_FINE_LOCATION.

אם המשתמש מעניק לאפליקציה הרשאת מיקום משוער, לאפליקציה תהיה גישה רק למיקום המשוער, ללא קשר להרשאות המיקום שהאפליקציה מצהירה עליהן.

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

שליחת בקשה לגישה למיקום בזמן הריצה

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

איור 1 מציג דוגמה לביצוע התהליך הזה. האפליקציה מכילה את התכונה 'שיתוף מיקום', שדורשת גישה למיקום בחזית. אבל האפליקציה לא מבקשת הרשאת מיקום עד שהמשתמש לוחץ על הלחצן Share location.

איור 1. תכונה לשיתוף מיקום שמחייבת גישה למיקום בחזית. הפיצ'ר מופעל אם המשתמש בוחר באפשרות רק כשהאפליקציה בשימוש.

המשתמש יכול להקצות רק מיקום משוער

ב-Android 12 (רמת API 31) ואילך, המשתמשים יכולים לבקש שהאפליקציה תאחזר רק פרטי מיקום משוער, גם כשהאפליקציה מבקשת את הרשאת זמן הריצה ל-ACCESS_FINE_LOCATION.

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

ACCESS_FINE_LOCATION must be requested with ACCESS_COARSE_LOCATION.

הערה: כדי לכבד את פרטיות המשתמשים, מומלץ לשלוח בקשה רק ל-ACCESS_COARSE_LOCATION. אפשר לעמוד ברוב התרחישים לדוגמה גם אם יש לכם גישה רק למידע משוער על המיקום. באיור 2 מוצגת תיבת הדו-שיח שמוצגת למשתמש כשהאפליקציה מטרגטת את Android 12 ומבקשת רק את ACCESS_COARSE_LOCATION.

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

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

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

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

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

איור 2. תיבת הדו-שיח של הרשאות המערכת שמופיעה כשהאפליקציה מבקשת רק את ההרשאה ACCESS_COARSE_LOCATION.

איור 3. תיבת דו-שיח של הרשאות מערכת שמופיעה כשהאפליקציה מבקשת גם את ההרשאה ACCESS_FINE_LOCATION וגם את ההרשאה ACCESS_COARSE_LOCATION בבקשה אחת בסביבת זמן ריצה.

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

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

	מדויק	משוער
בזמן השימוש באפליקציה	ACCESS_FINE_LOCATION וגם ACCESS_COARSE_LOCATION	ACCESS_COARSE_LOCATION
רק הפעם	ACCESS_FINE_LOCATION וגם ACCESS_COARSE_LOCATION	ACCESS_COARSE_LOCATION
דחייה	אין הרשאות מיקום	אין הרשאות מיקום

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

Kotlin

val locationPermissionRequest = registerForActivityResult(
        ActivityResultContracts.RequestMultiplePermissions()
    ) { permissions ->
        when {
            permissions.getOrDefault(Manifest.permission.ACCESS_FINE_LOCATION, false) -> {
                // Precise location access granted.
            }
            permissions.getOrDefault(Manifest.permission.ACCESS_COARSE_LOCATION, false) -> {
                // Only approximate location access granted.
            } else -> {
                // No location access granted.
            }
        }
    }

// ...

// Before you perform the actual permission request, check whether your app
// already has the permissions, and whether your app needs to show a permission
// rationale dialog. For more details, see Request permissions.
locationPermissionRequest.launch(arrayOf(
    Manifest.permission.ACCESS_FINE_LOCATION,
    Manifest.permission.ACCESS_COARSE_LOCATION))

Java

ActivityResultLauncher<String[]> locationPermissionRequest =
    registerForActivityResult(new ActivityResultContracts
        .RequestMultiplePermissions(), result -> {
            Boolean fineLocationGranted = result.getOrDefault(
                    Manifest.permission.ACCESS_FINE_LOCATION, false);
            Boolean coarseLocationGranted = result.getOrDefault(
                    Manifest.permission.ACCESS_COARSE_LOCATION,false);
            if (fineLocationGranted != null && fineLocationGranted) {
                // Precise location access granted.
            } else if (coarseLocationGranted != null && coarseLocationGranted) {
                // Only approximate location access granted.
            } else {
                // No location access granted.
            }
        }
    );

// ...

// Before you perform the actual permission request, check whether your app
// already has the permissions, and whether your app needs to show a permission
// rationale dialog. For more details, see Request permissions.
locationPermissionRequest.launch(new String[] {
    Manifest.permission.ACCESS_FINE_LOCATION,
    Manifest.permission.ACCESS_COARSE_LOCATION
});

בקשה לשדרוג למיקום המדויק

אתם יכולים לבקש מהמשתמש לשדרג את הגישה של האפליקציה ממיקום משוער למיקום מדויק. עם זאת, לפני שמבקשים מהמשתמש לשדרג את הגישה של האפליקציה למיקום המדויק, כדאי לבדוק אם רמת הדיוק הזו נדרשת בכלל בתרחיש לדוגמה של האפליקציה. אם האפליקציה שלכם צריכה להתאים מכשיר בקרבת מקום באמצעות Bluetooth או Wi-Fi, כדאי להשתמש בהתאמת מכשירים נלווים או בהרשאות ל-Bluetooth, במקום לבקש את ההרשאה ACCESS_FINE_LOCATION.

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

1. אם יש צורך, הסבירו למה האפליקציה זקוקה להרשאה.
2. מבקשים שוב את ההרשאות ACCESS_FINE_LOCATION ו-ACCESS_COARSE_LOCATION. מכיוון שהמשתמש כבר אישר למערכת להעניק לאפליקציה מיקום משוער, תיבת הדו-שיח של המערכת תהיה שונה הפעם, כפי שמוצג באיור 4 ובאיור 5:

איור 4. המשתמש בחר בעבר את האפשרויות אומדן ובזמן השימוש באפליקציה (בתיבת הדו-שיח מאיור 3).

איור 5. המשתמש בחר בעבר את האפשרויות אומדן ורק הפעם (בתיבת הדו-שיח מאיור 3).

בקשת מיקום בחזית בלבד

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

אזהרה: אם האפליקציה מטרגטת את Android מגרסה 11 (API ברמה 30) ואילך, המערכת אוכפת את השיטה המומלצת הזו. אם מבקשים הרשאת מיקום בחזית והרשאת מיקום ברקע בו-זמנית, המערכת מתעלמת מהבקשה ולא מעניקה לאפליקציה אף אחת מההרשאות.

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

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

התהליך לביצוע בקשות מצטברות הוא:

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

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

2. בשלב מאוחר יותר, כשהמשתמש ינסה תכונה שמחייבת גישה למיקום ברקע, תוכלו לבקש גישה למיקום ברקע.

בקשת מיקום ברקע במקרה הצורך

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

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

התוכן של תיבת הדו-שיח של ההרשאה תלוי בגרסת ה-SDK של היעד

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

אבל בגרסה Android 11 (רמת API 30) ואילך, תיבת הדו-שיח של המערכת לא כוללת את האפשרות Allow all all time. במקום זאת, המשתמשים צריכים להפעיל את המיקום ברקע בדף ההגדרות, כפי שמתואר באיור 7.

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

האפליקציה מטרגטת ל-Android מגרסה 11 ואילך

אם לא הוקצה לאפליקציה שלכם את ההרשאה ACCESS_BACKGROUND_LOCATION, והפונקציה shouldShowRequestPermissionRationale() מחזירה את הערך true, עליכם להציג למשתמשים ממשק משתמש חינוכי שכולל את הפרטים הבאים:

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

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

האפליקציה מטרגטת ל-Android מגרסה 10 ומטה

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

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

המשתמש יכול להשפיע על רמת הדיוק של המיקום ברקע

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

תזכורת על הרשאת מיקום ברקע

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

בודקים אם יש דרישות מיקום ביחסי התלות של ה-SDK של האפליקציה

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

מקורות מידע נוספים

מידע נוסף על הרשאות מיקום ב-Android זמין במאמרים הבאים:

שיעורי Lab

• שיטות מומלצות לשמירה על פרטיות

סרטונים

• איך לאתר שימוש אפשרי במיקום ברקע

דוגמיות

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