Aktualne miejsce

Za pomocą pakietu SDK Miejsc na Androida możesz odkrywać miejsca w bieżącej lokalizacji urządzenia. Przykłady miejsc to m.in. firmy lokalne, punkty orientacyjne i lokalizacje geograficzne.

Uwaga: aby zapoznać się z samouczkiem, skorzystaj z artykułu Samouczek dotyczący bieżącego miejsca.

Uprawnienia

Aby korzystać z biblioteki, nie musisz deklarować żadnych dodatkowych uprawnień w pliku manifestu aplikacji, ponieważ biblioteka deklaruje wszystkie uprawnienia, których używa, w swoim pliku manifestu. Jeśli jednak Twoja aplikacja korzysta z PlacesClient.findCurrentPlace(), musi poprosić o dostęp do lokalizacji w czasie działania.

Jeśli Twoja aplikacja nie używa uprawnienia PlacesClient.findCurrentPlace(), usuń jednoznacznie uprawnienia ACCESS_FINE_LOCATION i ACCESS_COARSE_LOCATION wprowadzone przez bibliotekę, dodając do pliku manifestu:

<manifest ... xmlns:tools="http://schemas.android.com/tools">
    ...
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove"/>
    ...
</manifest>

Dowiedz się więcej o  uprawnieniach i rozważ skorzystanie z usługi EasyPermissions.

Uzyskiwanie bieżącej lokalizacji

Aby znaleźć lokalną firmę lub inne miejsce, w którym znajduje się urządzenie, wykonaj te czynności:

1. Zadzwoń pod numer ContextCompat.checkSelfPermission, aby sprawdzić, czy użytkownik zezwolił na dostęp do lokalizacji urządzenia. Aplikacja musi też zawierać kod, który poprosi użytkownika o przyznanie uprawnień, a także przetworzy wynik. Więcej informacji znajdziesz w artykule Prośba o przyznanie uprawnień aplikacji.
2. Utwórz FindCurrentPlaceRequest, przekazując List Place.Field, określając typy danych o miejscach, o które aplikacja ma prosić.
3. Wywołaj funkcję PlacesClient.findCurrentPlace(), przekazując utworzony w poprzednim kroku obiekt FindCurrentPlaceRequest.
4. Pobierz listę PlaceLikelihood z FindCurrentPlaceResponse.

Uwaga: chociaż PlacesClient.fetchPlace()obsługuje wszystkie szczegóły miejsca, PlacesClient.findCurrentPlace()obsługuje tylko podzbiór szczegółów miejsca. Listę pól, których nie obsługuje pakiet findCurrentPlace(), znajdziesz w artykule Obsługa pól w pakiecie SDK Miejsc na Androida.

Pola odpowiadają wynikom wyszukiwania w miejscach i są podzielone na 3 kategorie rozliczeniowe: podstawowe, kontaktowe i atmosferyczne. Pole podstawowe jest rozliczane według stawki podstawowej i nie powoduje dodatkowych opłat. Pola Kontakt i Atmosfera są rozliczane według wyższej stawki. Więcej informacji o tym, jak naliczane są opłaty za wnioski o dane dotyczące miejsc, znajdziesz w artykule Wykorzystanie i rozliczenia.

Interfejs API zwracaFindCurrentPlaceResponsew Task. Obiekt FindCurrentPlaceResponse zawiera listę obiektów PlaceLikelihood, które reprezentują miejsca, w których urządzenie może się znajdować. W przypadku każdego miejsca wynik zawiera wskazanie prawdopodobieństwa, że to miejsce jest właściwe. Lista może być pusta, jeśli nie ma żadnego znanego miejsca odpowiadającego danej lokalizacji urządzenia.

Możesz wywołać funkcję PlaceLikelihood.getPlace(), aby pobrać obiekt Place, oraz funkcję PlaceLikelihood.getLikelihood(), aby uzyskać ocenę prawdopodobieństwa miejsca. Im wyższa wartość, tym większe prawdopodobieństwo, że miejsce jest najlepszym dopasowaniem.

Poniższy przykładowy kod pobiera listę miejsc, w których urządzenie znajduje się najprawdopodobniej, i rejestruje nazwę oraz prawdopodobieństwo każdego z nich.

Kotlin

// Use fields to define the data types to return.
val placeFields: List<Place.Field> = listOf(Place.Field.NAME)

// Use the builder to create a FindCurrentPlaceRequest.
val request: FindCurrentPlaceRequest = FindCurrentPlaceRequest.newInstance(placeFields)

// Call findCurrentPlace and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, permission.ACCESS_FINE_LOCATION) ==
    PackageManager.PERMISSION_GRANTED) {

    val placeResponse = placesClient.findCurrentPlace(request)
    placeResponse.addOnCompleteListener { task ->
        if (task.isSuccessful) {
            val response = task.result
            for (placeLikelihood: PlaceLikelihood in response?.placeLikelihoods ?: emptyList()) {
                Log.i(
                    TAG,
                    "Place '${placeLikelihood.place.name}' has likelihood: ${placeLikelihood.likelihood}"
                )
            }
        } else {
            val exception = task.exception
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }
    }
} else {
    // A local method to request required permissions;
    // See https://developer.android.com/training/permissions/requesting
    getLocationPermission()
}

      

Java

// Use fields to define the data types to return.
List<Place.Field> placeFields = Collections.singletonList(Place.Field.NAME);

// Use the builder to create a FindCurrentPlaceRequest.
FindCurrentPlaceRequest request = FindCurrentPlaceRequest.newInstance(placeFields);

// Call findCurrentPlace and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) {
    Task<FindCurrentPlaceResponse> placeResponse = placesClient.findCurrentPlace(request);
    placeResponse.addOnCompleteListener(task -> {
        if (task.isSuccessful()){
            FindCurrentPlaceResponse response = task.getResult();
            for (PlaceLikelihood placeLikelihood : response.getPlaceLikelihoods()) {
                Log.i(TAG, String.format("Place '%s' has likelihood: %f",
                    placeLikelihood.getPlace().getName(),
                    placeLikelihood.getLikelihood()));
            }
        } else {
            Exception exception = task.getException();
            if (exception instanceof ApiException) {
                ApiException apiException = (ApiException) exception;
                Log.e(TAG, "Place not found: " + apiException.getStatusCode());
            }
        }
    });
} else {
    // A local method to request required permissions;
    // See https://developer.android.com/training/permissions/requesting
    getLocationPermission();
}

      

Uwagi dotyczące wartości prawdopodobieństwa:

• Prawdopodobieństwo to względne prawdopodobieństwo, że dane miejsce jest najlepszym dopasowaniem na liście zwróconych miejsc w ramach pojedynczego żądania. Nie możesz porównywać prawdopodobieństw w różnych żądaniach.
• Wartość prawdopodobieństwa będzie się mieścić w przedziale od 0,0 do 1,0.

Na przykład, aby wskazać, że prawdopodobieństwo, że prawidłowym miejscem jest „Miejsce A” wynosi 55%, a prawdopodobieństwo, że jest to „Miejsce B” wynosi 35%, odpowiedź zawiera 2 elementy: „Miejsce A” z prawdopodobieństwo 0,55 i „Miejsce B” z prawdopodobieństwo 0,35.

Uwaga: więcej informacji o inicjowaniu interfejsu PlacesClient znajdziesz w artykule Inicjowanie klienta interfejsu Places API.

Możesz użyć CancellationToken, aby spróbować anulować żądanie do dowolnej klasy żądań (na przykład FetchPlaceRequest). Anulowanie odbywa się zgodnie z zasadą dołożenia wszelkich starań. Po wysłaniu prośby o anulowanie nie otrzymasz odpowiedzi. Wydanie tokena anulowania NIE gwarantuje, że konkretne żądanie zostanie anulowane. Możesz nadal zostać obciążony opłatą za żądanie, nawet jeśli nie otrzymasz odpowiedzi.

Wyświetlanie informacji o pochodzeniu danych w aplikacji

Gdy aplikacja wyświetla informacje uzyskane z PlacesClient.findCurrentPlace(), musi też wyświetlać informacje o źródłach. Zapoznaj się z dokumentacją dotyczącą przypisywania atrybucji.