Poproś o dostęp do lokalizacji

Aby chronić prywatność użytkowników, aplikacje korzystające z usług lokalizacyjnych muszą prosić o dostęp do lokalizacji.

Gdy prosisz o dostęp do lokalizacji, postępuj zgodnie z tymi samymi sprawdzonymi metodami jak w przypadku innych uprawnień środowiska wykonawczego. Jedną z ważnych różnic w przypadku uprawnień dotyczących lokalizacji jest to, że system obejmuje wiele uprawnień związanych z lokalizacją. Które uprawnienia i to, jak o nie poprosisz, zależą od wymagań dotyczących lokalizacji do konkretnego przypadku użycia.

Na tej stronie opisujemy różne typy wymagań dotyczących lokalizacji i oferujemy znajdziesz wskazówki, jak poprosić o dostęp do lokalizacji w każdym przypadku.

Rodzaje dostępu do lokalizacji

Każde uprawnienie ma kombinację tych cech:

• Kategoria: lokalizacja na pierwszym planie lub lokalizacja na tle.
• Dokładność: dokładna lub przybliżona lokalizacja.

Lokalizacja na pierwszym planie

Jeśli aplikacja zawiera funkcję, która udostępnia lub otrzymuje informacje o lokalizacji tylko raz lub przez określony czas, funkcja ta wymaga dostępu do lokalizacji na pierwszym planie. Oto kilka przykładów:

• Funkcja w aplikacji do nawigacji umożliwia użytkownikom wskazówek dojazdu.
• W aplikacji do obsługi wiadomości funkcja umożliwia użytkownikom udostępnianie bieżącej lokalizacji innemu użytkownikowi.

System uznaje aplikację za używaną lokalizację na pierwszym planie, jeśli funkcja aplikacja uzyskuje dostęp do bieżącej lokalizacji urządzenia w jednym z tych miejsc w sytuacjach:

• Aktywność należąca do Twojej aplikacji jest widoczna.

• Aplikacja uruchamia usługę na pierwszym planie. Gdy usługa na pierwszym planie jest uruchomiona, system informuje o tym użytkownika, wyświetlając stałe powiadomienie. Aplikacja zachowuje dostęp, gdy jest działająca w tle, np. użytkownik naciska przycisk ekranu głównego na urządzeniu lub obraca ekran wyłączone.

  Dodatkowo zalecamy zadeklarowanie typu usługi na pierwszym planie location, jak w tym fragmencie kodu. W Androidzie 10 (poziom interfejsu API 29) i nowszych należy zadeklarować ten typ usługi na pierwszym planie.

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

Deklarujesz potrzebę dostępu do lokalizacji na pierwszym planie, gdy aplikacja wysyła żądanie ACCESS_COARSE_LOCATION lub ACCESS_FINE_LOCATION zgodnie z tym fragmentem:

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

Lokalizacja w tle

Aplikacja wymaga dostępu do lokalizacji w tle, jeśli jej funkcja stale udostępnia lokalizację innym użytkownikom lub korzysta z interfejsu API do tworzenia geoogrodzenia. Oto kilka przykładów:

• Funkcja w aplikacji do udostępniania lokalizacji w grupie rodzinnej pozwala użytkownikom udostępniać lokalizację członkom rodziny.
• W aplikacji IoT funkcja umożliwia użytkownikom konfigurowanie urządzeń domowych w taki sposób, aby wyłączały się, gdy użytkownik wyjdzie z domu, i znów włączyły, gdy wróci.

System uznaje, że aplikacja korzysta z lokalizacji w tle, jeśli uzyskuje dostęp do bieżącej lokalizacji urządzenia w sytuacji innej niż opisana w sekcji Lokalizacja na pierwszym planie. Dokładność lokalizacji w tle wynosi taką samą jak dokładność lokalizacji na pierwszym planie, która zależy od uprawnienia dostępu do lokalizacji deklarowane przez aplikację.

W Androidzie 10 (poziom interfejsu API 29) i nowszych musisz zadeklarować ACCESS_BACKGROUND_LOCATION uprawnienia w pliku manifestu aplikacji, aby poprosić o dostęp do lokalizacji w tle dostępu podczas działania. W starszych wersjach Androida, gdy aplikacja uzyska dostęp do lokalizacji na pierwszym planie, automatycznie uzyska też dostęp do lokalizacji w tle.

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

Dokładność

Android obsługuje te poziomy dokładności lokalizacji:

W przybliżeniu

Podaje przybliżoną lokalizację urządzenia. Jeśli szacowana lokalizacja pochodzi z usługi LocationManagerService lub FusedLocationProvider, jest ona dokładna do około 3 kilometrów kwadratowych (około 1,2 mil kwadratowych). Aplikacja może otrzymywać lokalizacje z taką dokładnością, jeśli: zadeklarować uprawnienie ACCESS_COARSE_LOCATION, ale nie ACCESS_FINE_LOCATION.

Dokładnie

Udostępnia najdokładniejszą orientacyjną lokalizację urządzenia. Jeśli szacowana lokalizacja pochodzi z LocationManagerService lub FusedLocationProvider, szacowanie jest zwykle dokładne do około 50 metrów, a czasami nawet do kilku metrów. Jeśli zadeklarujesz uprawnienie ACCESS_FINE_LOCATION, Twoja aplikacja może otrzymywać lokalizację z taką dokładnością.

Jeśli użytkownik przyzna dostęp do przybliżonej lokalizacji, aplikacja ma dostęp tylko do przybliżonej lokalizacji, niezależnie od tego, uprawnienia deklarowane przez aplikację.

Aplikacja powinna działać, gdy użytkownik zezwoli na dostęp do przybliżonej lokalizacji. Jeśli funkcja w aplikacji wymaga dostępu do dokładnej lokalizacji za pomocą uprawnienia ACCESS_FINE_LOCATION, możesz poprosić użytkownika, aby zezwolił aplikacji na dostęp do dokładnej lokalizacji.

Wysyłanie prośby o dostęp do lokalizacji podczas działania

Jeśli funkcja w aplikacji wymaga dostępu do lokalizacji, poczekaj, aż użytkownik zacznie z niej korzystać, a dopiero potem poproś o uprawnienia. Ten proces jest zgodny ze sprawdzoną metodą polegającą na prośbach o uprawnienia w kontekście, opisaną w przewodniku Prośby o uprawnienia aplikacji.

Ilustracja 1 pokazuje, jak to zrobić. Aplikacja zawiera funkcję „udostępnianie lokalizacji”, która wymaga dostępu do lokalizacji na pierwszym planie. Aplikacja nie prosi o dostęp do lokalizacji, dopóki użytkownik nie wybierze Przycisk udostępniania lokalizacji.

Użytkownik może udostępnić tylko przybliżoną lokalizację.

W systemie Android 12 (poziom API 31) lub nowszym użytkownicy mogą poprosić aplikację o pobieranie tylko przybliżonych informacji o lokalizacji, nawet jeśli aplikacja poprosi o uprawnienia w czasie działania.

Aby uwzględnić to potencjalne zachowanie użytkownika, nie wysyłaj żądania ACCESS_FINE_LOCATION lub zgodę na wykorzystanie danych. Zamiast tego poproś o przyznanie obu uprawnień: ACCESS_FINE_LOCATION i ACCESS_COARSE_LOCATION w jednym żądaniu w czasie wykonywania. Jeśli spróbujesz wysłać prośbę tylko o ACCESS_FINE_LOCATION, system ignoruje żądanie w niektórych wersjach Android 12. Jeśli Twoja aplikacja jest kierowana na Androida 12 lub nowszego, system rejestruje w Logcat ten komunikat o błędzie:

ACCESS_FINE_LOCATION must be requested with ACCESS_COARSE_LOCATION.

Gdy aplikacja poprosi zarówno ACCESS_FINE_LOCATION, jak i ACCESS_COARSE_LOCATION, okno uprawnień systemowych zawiera te opcje:

• Dokładna: aplikacja może uzyskać dokładne informacje o lokalizacji.
• Przybliżona: aplikacja może uzyskać tylko przybliżone informacje o lokalizacji.

Rysunek 3 pokazuje, że okno zawiera wizualne wskazówki dotyczące obu opcji, aby ułatwić użytkownikowi dokonanie wyboru. Po wybraniu dokładności lokalizacji użytkownik klika jeden z 3 przycisków, aby wybrać czas trwania udzielonego uprawnienia.

W Androidzie 12 i nowszych użytkownicy mogą przejść do ustawień systemu, aby ustawić preferowaną dokładność lokalizacji dla dowolnej aplikacji, niezależnie od wersji docelowego pakietu SDK tej aplikacji. To ograniczenie obowiązuje nawet wtedy, gdy aplikacja jest zainstalowana na urządzeniu z Androidem 11 lub niższym, a użytkownik zaktualizuje urządzenie do wersji Android 12 lub nowszej.

Wybór użytkownika wpływa na przyznawanie uprawnień

W tabeli poniżej znajdziesz uprawnienia przyznawane aplikacji przez system. na podstawie opcji wybranych przez użytkownika w oknie dialogowym uprawnień w czasie działania:

Aby sprawdzić, jakie uprawnienia system przyznał aplikacji, sprawdź wartość zwracaną przez prośbę o uprawnienia. W kodzie możesz użyć bibliotek Jetpacka podobnych do tego przykładu lub bibliotek platformy, w których samodzielnie zarządzasz kodem prośby o uprawnienia.

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

Poproś o podniesienie dokładnej lokalizacji

Możesz poprosić użytkownika o zmianę uprawnień dostępu aplikacji z przybliżonej lokalizacji na dokładną lokalizację. Zanim poprosisz użytkownika o udostępnienie aplikacji dostępu do dokładnej lokalizacji, zastanów się, czy w danym przypadku konieczny jest taki poziom dokładności. Jeśli aplikacja musi sparować urządzenie z urządzeniami w pobliżu urządzeń przez Bluetooth lub Wi-Fi, rozważ zastosowanie urządzenia towarzyszącego parowanie lub Bluetooth , a nie prosi o uprawnienie ACCESS_FINE_LOCATION.

Aby poprosić użytkownika o zmianę z przybliżonego na dokładny dostępu aplikacji do lokalizacji:

1. Jeśli to konieczne, wyjaśnij, dlaczego Twoja aplikacja wymaga .
2. Poproś o uprawnienia ACCESS_FINE_LOCATION i ACCESS_COARSE_LOCATION ponownie. Użytkownik zezwolił już systemowi na udostępnienie aplikacji przybliżonej lokalizacji, więc tym razem okno systemu będzie wyglądać inaczej niż na rysunku 4 i rysunku 5:

Początkowo żądaj tylko lokalizacji na pierwszym planie

Nawet jeśli kilka funkcji w aplikacji wymaga dostępu do lokalizacji, prawdopodobnie tylko niektóre z nich wymagają dostępu do lokalizacji w tle. Dlatego zalecamy, aby aplikacja wysyłała stopniowe żądania dostępu do lokalizacji, prosząc najpierw o dostęp do lokalizacji na pierwszym planie, a potem w tle. Dzięki żądaniom stopniowym użytkownicy zyskują większą kontrolę i przejrzystość, ponieważ mogą lepiej zrozumieć, które funkcje aplikacji potrzebują dostępu do lokalizacji w tle.

Na rysunku 6. widać przykład aplikacji, która obsługuje dodatkowe żądania. Zarówno opcja „Pokaż bieżącą lokalizację”, i „poleć miejsca w pobliżu” funkcje wymagają dostępu do lokalizacji na pierwszym planie. Tylko funkcja „polecanie miejsc w pobliżu” wymaga dostępu do lokalizacji w tle.

Proces wykonywania żądań przyrostowych wygląda tak:

1. Aplikacja powinna najpierw kierować użytkowników do funkcji, które wymagają dostępu do lokalizacji na pierwszym planie, takich jak funkcja „Udostępnij lokalizację” na rysunku 1 lub funkcja „Pokaż aktualną lokalizację” na rysunku 2.

   Zalecamy wyłączenie dostępu użytkowników do funkcji, które wymagają dostępu do lokalizacji w tle, dopóki aplikacja nie będzie mieć dostępu do lokalizacji na pierwszym planie.

2. Później, gdy użytkownik zapozna się z funkcjami, które wymagają dostęp do lokalizacji w tle, możesz żądanie lokalizacji w tle dostęp.

W razie potrzeby poproś o dostęp do lokalizacji w tle

Zawartość okna uprawnień zależy od docelowej wersji pakietu SDK

Gdy funkcja aplikacji prosi o dostęp do lokalizacji w tle na urządzeniu, które działa Android 10 (poziom interfejsu API 29) w oknie uprawnień systemu znajduje się opcja o nazwie Zawsze zezwalaj. Jeśli użytkownik wybierze tę opcję, funkcja w aplikacja uzyskuje dostęp do lokalizacji w tle.

W Androidzie 11 (poziom interfejsu API 30) i nowszych opcja Zawsze zezwalaj nie jest jednak dostępna w oknie dialogowym systemu. Zamiast tego użytkownicy muszą włączyć działanie w tle lokalizację na stronie ustawień, jak widać na rysunku 7.

Możesz pomóc użytkownikom dotrzeć do tej strony ustawień, stosując sprawdzone metody podczas żądania uprawnienia do korzystania z lokalizacji w tle. Proces przyznawania uprawnień zależy od docelowej wersji pakietu SDK aplikacji.

Aplikacja jest kierowana na Androida 11 lub nowszego

Jeśli Twoja aplikacja nie ma uprawnienia ACCESS_BACKGROUND_LOCATION, a shouldShowRequestPermissionRationale()zwraca wartość true, wyświetl użytkownikom interfejs edukacyjny, który zawiera:

• jasne wyjaśnienie, dlaczego funkcja aplikacji potrzebuje dostępu do lokalizacji w tle;
• Widoczna dla użytkownika etykieta opcji ustawień, która umożliwia dostęp do lokalizacji w tle. (na przykład Zawsze zezwalaj na ilustracji 7). Aby uzyskać tę etykietę, zadzwoń pod numer getBackgroundPermissionOptionLabel(). Wartość zwracana przez tę metodę jest dostosowywana do preferowanego języka urządzenia użytkownika.
• opcja odmowy uprawnień przez użytkowników; Jeśli użytkownicy odrzucili tło dostępu do lokalizacji, powinien mieć możliwość dalszego korzystania z aplikacji.

Aplikacja jest kierowana na Androida 10 lub starszego

Gdy funkcja aplikacji poprosi o dostęp do lokalizacji w tle, użytkownicy zobaczą okno systemu. W tym oknie jest opcja przejścia na stronę ustawień, na której można wybrać opcje dotyczące dostępu do lokalizacji.

O ile Twoja aplikacja jest już zgodna ze sprawdzonymi metodami przesyłania próśb o lokalizację uprawnień, nie musisz jednak wprowadzać żadnych zmian, aby umożliwić takie działanie.

Użytkownik może wpływać na dokładność lokalizacji w tle

Jeśli użytkownik prosi o przybliżoną lokalizację, dane opcje w oknie dostępu do lokalizacji mają też zastosowanie do lokalizacji w tle. W Innymi słowy, jeśli użytkownik przyzna aplikacji ACCESS_BACKGROUND_LOCATION dostępu, ale zezwala jedynie na dostęp do przybliżonej lokalizacji na pierwszym planie, aplikacja ma również dostęp do przybliżonej lokalizacji w tle.

Przypomnienie o przyznaniu lokalizacji w tle

Na Androidzie 10 i nowszych, gdy funkcja aplikacji uzyskuje dostęp do lokalizacji urządzenia w Działanie w tle po raz pierwszy od momentu przyznania przez użytkownika lokalizacji w tle system planuje wysłanie powiadomienia do użytkownika. To powiadomienie przypomina użytkownikowi, że zezwolił aplikacji na stały dostęp do lokalizacji urządzenia. Przykładowe powiadomienie wyświetla się na rys. 8.

Sprawdź wymagania dotyczące lokalizacji w zależnościach pakietu SDK aplikacji

Sprawdź, czy Twoja aplikacja korzysta z pakietów SDK, które wymagają dostępu do lokalizacji, w szczególności uprawnienia ACCESS_FINE_LOCATION. Przeczytaj ten artykuł na Medium o zależnościach pakietu SDK.

Dodatkowe materiały

Więcej informacji o uprawnieniach dostępu do lokalizacji na Androidzie znajdziesz w tych materiałach:

Ćwiczenia z programowania

• Sprawdzone metody ochrony prywatności

Filmy

• Jak znaleźć możliwą lokalizację w tle wykorzystanie

Próbki

• Przykładowa aplikacja, która demonstruje używanie uprawnień dostępu do lokalizacji.