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

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

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

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

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

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

מיקום בחזית

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

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

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

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

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

    בנוסף, מומלץ להצהיר על סוג של שירות שפועל בחזית מסוג 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>

דיוק

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

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

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

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

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

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

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

אחרי שהמשתמש לוחץ על הלחצן &#39;שיתוף המיקום&#39;, מופיעה תיבת הדו-שיח של הרשאת המיקום של המערכת
איור 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_FINE_LOCATION וגם את ההרשאה ACCESS_COARSE_LOCATION, תיבת הדו-שיח של הרשאות המערכת כוללת את האפשרויות הבאות למשתמש:

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

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

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

תיבת הדו-שיח מתייחסת רק למיקום המשוער, והיא מכילה 3 לחצנים, אחד מעל השני
איור 2. תיבת הדו-שיח של הרשאות המערכת שמופיעה כשהאפליקציה מבקשת רק את ההרשאה ACCESS_COARSE_LOCATION.
בתיבת הדו-שיח יש 2 קבוצות של אפשרויות, אחת מעל השנייה
איור 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:
תיבת הדו-שיח מכילה את האפשרויות &#39;שינוי למיקום המדויק&#39;, &#39;רק הפעם&#39; ו&#39;דחייה&#39;.
איור 4. המשתמש בחר בעבר באפשרות משוער ובאפשרות בזמן השימוש באפליקציה (בתיבת הדו-שיח מאיור 3).
בתיבת הדו-שיח מופיעות האפשרויות &#39;רק הפעם&#39; ו&#39;דחייה&#39;.
איור 5. המשתמש בחר בעבר באפשרות משוער ובאפשרות רק הפעם (בתיבת הדו-שיח מאיור 3).

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

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

באיור 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

סרטונים

דוגמיות

הקודם
About user location
הבא
Get the last known location