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, co w przypadku innych uprawnień czasu działania. Ważna różnica dotycząca dostępu do lokalizacji polega na tym, że system obejmuje wiele uprawnień związanych z lokalizacją. Wymagania dotyczące lokalizacji i sposób ich zgłaszania zależą od wymagań dotyczących lokalizacji w przypadku danego przypadku użycia aplikacji.

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

Rodzaje dostępu do lokalizacji

Każde uprawnienie ma kombinację tych cech:

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

Lokalizacja na pierwszym planie

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

• Funkcja w aplikacji do nawigacji, która umożliwia użytkownikom otrzymywanie szczegółowych 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, że aplikacja używa lokalizacji na pierwszym planie, jeśli jej funkcja uzyskuje dostęp do bieżącej lokalizacji urządzenia w jednym z tych przypadków:

• 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 użytkowników o tym, wyświetlając trwałe powiadomienie. Aplikacja zachowuje dostęp, gdy jest uruchomiona w tle, np. gdy użytkownik naciśnie przycisk Home na urządzeniu lub wyłączy jego wyświetlacz.

  Dodatkowo zalecamy zadeklarowanie typu usługi na pierwszym planie location, jak pokazano w tym fragmencie kodu. W Androidzie 10 (poziom interfejsu API 29) i nowszych musisz 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 prosi o ACCESS_COARSE_LOCATION lub ACCESS_FINE_LOCATION uprawnienia, jak pokazano w tym fragmencie kodu:

<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 na bieżąco udostępniać lokalizację członkom grupy rodzinnej.
• Funkcja w aplikacji IoT umożliwia użytkownikom takie skonfigurowanie urządzeń domowych, aby wyłączały się, gdy użytkownik wychodziły z domu, i włączały się ponownie, gdy użytkownik wraca do domu.

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 jest taka sama jak dokładność lokalizacji na pierwszym planie, która zależy od deklarowanych przez aplikację uprawnień do lokalizacji.

W Androidzie 10 (interfejs API na poziomie 29) i nowszych musisz zadeklarować uprawnienie ACCESS_BACKGROUND_LOCATION w pliku manifestu aplikacji, aby poprosić o dostęp do lokalizacji w tle w czasie działania. We wcześniejszych wersjach Androida aplikacja automatycznie uzyskuje również dostęp do lokalizacji na pierwszym planie, gdy otrzymuje 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 następujące 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). Jeśli zadeklarujesz uprawnienie ACCESS_COARSE_LOCATION, Twoja aplikacja może otrzymywać lokalizacje z taką dokładnością, ale nie ACCESS_FINE_LOCATION.

Dokładnie

Udostępnia najdokładniejszą orientacyjną lokalizację urządzenia. Jeśli lokalizacja szacowana jest z LocationManagerService lub FusedLocationProvider, zwykle mieści się w odległości około 50 metrów, a czasami jest równie dokładna, jak kilka metrów (10 metrów) lub nawet lepsza. Jeśli zadeklarujesz uprawnienie ACCESS_FINE_LOCATION, Twoja aplikacja może otrzymywać dane o lokalizacji z taką dokładnością.

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

Aplikacja powinna działać, gdy użytkownik przyzna 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.

Prośba o dostęp do lokalizacji w czasie działania aplikacji

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, jak opisano w przewodniku Prośby o uprawnienia aplikacji.

Rysunek 1 przedstawia przykładowy sposób wykonania tej procedury. Aplikacja zawiera funkcję „udostępnianie lokalizacji”, która wymaga dostępu do lokalizacji na pierwszym planie. Aplikacja nie poprosi o dostęp do lokalizacji, dopóki użytkownik nie kliknie przycisku Udostępnij lokalizację.

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

W Androidzie 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 uniknąć takiego zachowania użytkowników, nie proś o same uprawnienia ACCESS_FINE_LOCATION. Zamiast tego poproś o uprawnienia ACCESS_FINE_LOCATION i ACCESS_COARSE_LOCATION w jednym żądaniu w czasie wykonywania. Jeśli spróbujesz wysłać prośbę tylko z parametrem ACCESS_FINE_LOCATION, system zignoruje ją w niektórych wersjach Androida 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 prosi o uprawnienia ACCESS_FINE_LOCATION i ACCESS_COARSE_LOCATION, w oknie uprawnień systemowych użytkownik ma do wyboru 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 przyznanie uprawnień

Poniższa tabela zawiera uprawnienia, które system przyznaje aplikacji na podstawie opcji wybranych przez użytkownika w oknie uprawnień:

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

Prośba o uaktualnienie do dokładnej lokalizacji

Możesz poprosić użytkownika o zmianę dostępu do aplikacji z przybliżonej 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 Twoja aplikacja musi sparować urządzenie z urządzeniami w pobliżu za pomocą Bluetootha lub Wi-Fi, zamiast żądać uprawnienia ACCESS_FINE_LOCATION, rozważ użycie parowania z urządzeniem towarzyszącym lub uprawnień Bluetootha.

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

1. W razie potrzeby wyjaśnij, dlaczego Twoja aplikacja potrzebuje tego uprawnienia.
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. Funkcje „Pokaż bieżącą lokalizację” i „Poleć miejsca w pobliżu” 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:

1. Na początku aplikacja powinna 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. Gdy użytkownik będzie korzystać z funkcji, która wymaga dostępu do lokalizacji w tle, możesz poprosić o dostęp do lokalizacji w tle.

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

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

Gdy funkcja w aplikacji prosi o dostęp do lokalizacji w tle na urządzeniu z Androidem 10 (poziom interfejsu API 29), w oknie uprawnień systemowych jest dostępna opcja Zawsze zezwalaj. Jeśli użytkownik wybierze tę opcję, funkcja aplikacji uzyska 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ć lokalizację w tle na stronie ustawień, jak pokazano na rys. 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 otrzymała uprawnienia ACCESS_BACKGROUND_LOCATION, a shouldShowRequestPermissionRationale() zwraca true, pokaż użytkownikom interfejs edukacyjny zawierający te informacje:

• jasne wyjaśnienie, dlaczego funkcja aplikacji potrzebuje dostępu do lokalizacji w tle;
• Etykieta opcji ustawień widoczna dla użytkownika, która umożliwia dostęp do lokalizacji w tle (np. Zawsze zezwalaj na rysunku 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 odmówią udostępnienia dostępu do lokalizacji w tle, powinni nadal mieć możliwość korzystania z aplikacji.

Aplikacja jest kierowana na Androida 10 lub starszego

Gdy funkcja w aplikacji prosi o dostęp do lokalizacji w tle, użytkownicy widzą okno systemu. To okno zawiera opcję przejścia do opcji dostępu do lokalizacji dla aplikacji na stronie ustawień.

Jeśli Twoja aplikacja już stosuje się do sprawdzonych metod dotyczących żądania uprawnień do lokalizacji, nie musisz wprowadzać żadnych zmian, aby obsługiwać tę funkcję.

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

Jeśli użytkownik poprosi o przybliżoną lokalizację, jego wybory w oknie z prośbą o dostęp do lokalizacji będą miały zastosowanie również do lokalizacji w tle. Innymi słowy, jeśli użytkownik przyzna aplikacji uprawnienie ACCESS_BACKGROUND_LOCATION, ale tylko do przybliżonej lokalizacji na pierwszym planie, aplikacja będzie miała dostęp tylko do przybliżonej lokalizacji w tle.

Przypomnienie o przyznaniu dostępu do lokalizacji w tle

W Androidzie 10 i nowszych, gdy funkcja w aplikacji po raz pierwszy uzyska dostęp do lokalizacji urządzenia w tle po tym, jak użytkownik przyznał uprawnienia do dostępu do lokalizacji w tle, system zaplanował wysłanie powiadomienia do użytkownika. To powiadomienie przypomina użytkownikowi, że zezwolił aplikacji na stały dostęp do lokalizacji urządzenia. Rysunek 8 przedstawia przykładowe powiadomienie.

Sprawdzanie wymagań dotyczących lokalizacji w zależnych pakietach SDK aplikacji

Sprawdź, czy Twoja aplikacja korzysta z pakietów SDK zależnych od dostępu do lokalizacji (a zwłaszcza z 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 sprawdzić, czy aplikacja używa lokalizacji w tle

Próbki

• Przykładowa aplikacja demonstrująca korzystanie z dostępu do lokalizacji.