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

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

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

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

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

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

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

מיקום בחזית

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

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

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

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

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

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

מיקום ברקע

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

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

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

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

ACCESS_FINE_LOCATION must be requested with ACCESS_COARSE_LOCATION.

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

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

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

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

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

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

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

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))

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:

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

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

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

כך מבצעים בקשות מצטברות:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

שיעורי Lab

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

סרטונים

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

דוגמיות

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