דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

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

מיקום בחזית

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

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

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

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

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


<service
    android:name="MyNavigationService"
    android:foregroundServiceType="location" ... >
    
</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 מציג דוגמה לביצוע התהליך הזה. האפליקציה מכילה את התכונה 'שיתוף מיקום', שדורשת גישה למיקום בחזית. עם זאת, האפליקציה לא מבקשת את הרשאת המיקום עד שהמשתמש לוחץ על הלחצן שיתוף המיקום.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Codelabs

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

סרטונים

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

דוגמיות

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

About user location

Get the last known location