Autouzupełnianie miejsc

Usługa autouzupełniania w pakiecie Places SDK na Androida zwraca prognozy dotyczące miejsc w odpowiedzi na zapytania użytkowników. Gdy użytkownik wpisze coś na klawiaturze, usługa autouzupełniania zwróci sugestie dotyczące miejsc takich jak firmy, adresy, kod pocztowy czy punkty zainteresowania.

Autouzupełnianie możesz dodać do aplikacji na te sposoby:

• Dodaj widget autouzupełniania, aby skrócić czas programowania i zapewnić spójne środowisko użytkownika.
• Pobierz prognozy dotyczące miejsc w ramach automatyzacji, aby zapewnić użytkownikom spersonalizowane wrażenia.

Dodawanie widżetu autouzupełniania

Widżet autouzupełniania to okno wyszukiwania z wbudowaną funkcją autouzupełniania. Gdy użytkownik wpisze hasła wyszukiwania, widżet wyświetli listę przewidywanych miejsc do wyboru. Gdy użytkownik dokona wyboru, zwrócony zostanie obiekt Place, którego aplikacja może użyć do uzyskania szczegółowych informacji o wybranym miejscu.

Dodanie widżetu autouzupełniania do aplikacji jest możliwe na 2 sposoby:

• Opcja 1. Umieść AutocompleteSupportFragment.
• Opcja 2. Użyj intencji do uruchomienia działania autouzupełniania.

Opcja 1. Wstawianie fragmentu AutocompleteSupportFragment

Aby dodać AutocompleteSupportFragment do aplikacji:

1. Dodaj fragment do układu XML swojej aktywności.
2. Dodaj listenera do aktywności lub fragmentu.

Dodawanie fragmentu AutocompleteSupportFragment do aktywności

Aby dodać AutocompleteSupportFragment do aktywności, dodaj nowy fragment do układu XML. Na przykład:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />

• Domyślnie fragment nie ma obramowania ani tła. Aby zapewnić spójny wygląd wizualny, zagnieżdż fragment w innym elemencie układu, takim jak CardView.
• Jeśli używasz fragmentu Autouzupełnianie i musisz zastąpić zmienną onActivityResult, musisz wywołać funkcję super.onActivityResult, w przeciwnym razie fragment nie będzie działać prawidłowo.

Dodawanie interfejsu PlaceSelectionListener do aktywności

Funkcja PlaceSelectionListener zwraca miejsce w odpowiedzi na wybór użytkownika. Ten kod pokazuje, jak utworzyć odwołanie do fragmentu i dodać do niego listenera:AutocompleteSupportFragment

    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
                as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
            getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

Opcja 2. Użyj zamiaru do uruchomienia aktywności autouzupełniania

Jeśli chcesz, aby Twoja aplikacja używała innego sposobu nawigacji (np. aby wywołać funkcję autouzupełniania za pomocą ikony, a nie pola wyszukiwania), może ona uruchomić autouzupełnianie za pomocą intencji.

Aby uruchomić widżet autouzupełniania za pomocą intencji:

1. Użyj instrukcji Autocomplete.IntentBuilder, aby utworzyć intencję, przekazując żądany tryb Autocomplete.
2. Zdefiniuj funkcję wywołania wyniku aktywności registerForActivityResult, która może służyć do uruchamiania intencji i obsługi przewidywanego miejsca wybranego przez użytkownika w wyniku.

Tworzenie intencji autouzupełniania

W tym przykładzie użyliśmy Autocomplete.IntentBuilder, aby utworzyć zamiar uruchamiający widget autouzupełniania:

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startAutocomplete.launch(intent)

      

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .build(this);
    startAutocomplete.launch(intent);

      

Jeśli używasz intencji do uruchamiania widżetu autouzupełniania, możesz wybrać tryb wyświetlania nakładki lub tryb pełnoekranowy. Na poniższych zrzutach ekranu widać poszczególne tryby wyświetlania:

Rejestrowanie wywołania zwrotnego dla wyniku intencji

Aby otrzymywać powiadomienie, gdy użytkownik wybierze miejsce, zdefiniuj element registerForActivityResult(), który uruchamia aktywność i także obsługuje wynik, jak pokazano w tym przykładzie. Jeśli użytkownik wybrał prognozę, zostanie ona dostarczona w zamierzeniu zawartym w obiekcie wyniku. Ponieważ intencja została utworzona przez Autocomplete.IntentBuilder, metoda Autocomplete.getPlaceFromIntent() może wyodrębnić z niej obiekt Miejsce.

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            Log.i(TAG, "User canceled autocomplete")
        }
    }

      

private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

      

Pobieranie prognoz dotyczących miejsc za pomocą programowania

Możesz utworzyć niestandardowy interfejs wyszukiwania jako alternatywę dla interfejsu udostępnianego przez widget autouzupełniania. Aby to zrobić, aplikacja musi uzyskać prognozy dotyczące miejsc za pomocą programowania. Twoja aplikacja może uzyskać listę przewidywanych nazw miejsc lub adresów z interfejsu autocomplete API, wywołując element PlacesClient.findAutocompletePredictions(), przekazując obiekt FindAutocompletePredictionsRequest z tymi parametrami:

• Wymagany: ciąg tekstowy query zawierający tekst wpisany przez użytkownika.
• Zalecane: plik AutocompleteSessionToken, który grupowałby fazy zapytania i wyboru w ramach wyszukiwania użytkownika w oddzielną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, a kończy, gdy wybierze miejsce.
• Zalecany: obiekt RectangularBounds, który określa granice szerokości i długości geograficznej, aby ograniczać wyniki do określonego regionu.
• Opcjonalnie: co najmniej 2-literowe kody krajów (ISO 3166-1, alfa-2), wskazujące kraje, w których wyniki mają być ograniczone.

• Opcjonalnie: TypeFilter, które możesz użyć, aby ograniczyć wyniki do określonego typu miejsca. Obsługiwane są te typy miejsc:

  • TypeFilter.GEOCODE – zwraca tylko wyniki geokodowania, a nie firmy. Użyj tego żądania, aby rozstrzygnąć wyniki, gdy wskazana lokalizacja może być niejednoznaczna.
  • TypeFilter.ADDRESS – zwraca tylko wyniki autouzupełniania z dokładnym adresem. Użyj tego typu, jeśli wiesz, że użytkownik szuka dokładnie określonego adresu.
  • TypeFilter.ESTABLISHMENT – zwraca tylko miejsca, które są firmami.

  • TypeFilter.REGIONS – zwraca tylko miejsca pasujące do jednego z tych typów:

  • LOCALITY

  • SUBLOCALITY

  • POSTAL_CODE

  • COUNTRY

  • ADMINISTRATIVE_AREA_LEVEL_1

  • ADMINISTRATIVE_AREA_LEVEL_2

  • TypeFilter.CITIES – zwraca tylko wyniki pasujące do LOCALITY lub ADMINISTRATIVE_AREA_LEVEL_3.

• Opcjonalnie: LatLng określający lokalizację, z której pochodzi żądanie. Gdy wywołasz setOrigin(), usługa zwraca w odpowiedzi odległość w metrach (distanceMeters) od określonego miejsca pochodzenia dla każdej prognozy autouzupełniania.

Informacje o typach miejsc znajdziesz w przewodniku Typy miejsc.

Przykład poniżej pokazuje pełne wywołanie funkcji PlacesClient.findAutocompletePredictions().

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }

      

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(new LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

Interfejs API zwraca FindAutocompletePredictionsResponsew  Task. Plik FindAutocompletePredictionsResponse zawiera listę AutocompletePrediction obiektów reprezentujących przewidywane miejsca. Lista może być pusta, jeśli nie ma żadnych znanych miejsc pasujących do zapytania i kryteriów filtra.

Aby pobrać szczegóły przewidywanego miejsca, możesz wywołać te metody:

• getFullText(CharacterStyle)zwraca pełny tekst opisu miejsca. Jest to kombinacja tekstu głównego i dodatkowego. Przykład: „Wieża Eiffla, Avenue Anatole France, Paryż, Francja”. Ponadto ta metoda umożliwia wyróżnienie sekcji opisu, które pasują do wyszukiwania, za pomocą wybranego stylu (CharacterStyle). Parametr CharacterStyle jest opcjonalny. Jeśli nie potrzebujesz podświetlenia, ustaw tę wartość jako null.
• getPrimaryText(CharacterStyle)zwraca główny tekst opisujący miejsce. Zwykle jest to nazwa miejsca. Przykłady: „Wieża Eiffla” lub „123 ul. Pitt”.
• getSecondaryText(CharacterStyle)zwraca tekst dodatkowy w opisie miejsca. Jest to przydatne, na przykład w przypadku wyświetlania przewidywanej odpowiedzi na drugim wierszu. Przykłady: „Avenue Anatole France, Paris, France” i „Sydney, New South Wales”.
• getPlaceId()zwraca identyfikator miejsca przewidywanego miejsca. Identyfikator miejsca to tekstowy identyfikator jednoznacznie identyfikujący miejsce, którego możesz użyć do ponownego pobrania obiektu Place. Więcej informacji o identyfikatorach miejsc w pakiecie Places SDK na Androida znajdziesz w sekcji Szczegóły miejsca. Ogólne informacje o identyfikatorach miejsc znajdziesz w artykule Omówienie identyfikatorów miejsc.
• getPlaceTypes()zwraca listę typów miejsc powiązanych z tym miejscem.
• getDistanceMeters()zwraca w metrach odległość w linii prostej między tym miejscem a punktem początkowym określonym w żądaniu.

Tokeny sesji

Tokeny sesji łączą fazy zapytania i wyboru w wyszukiwaniu autouzupełniania użytkownika w jedną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, a kończy, gdy wybierze miejsce. Każda sesja może zawierać wiele zapytań, po których następuje wybór jednego miejsca. Po zakończeniu sesji token traci ważność. Aplikacja musi wygenerować nowy token na każdą sesję. Zalecamy używanie tokenów sesji we wszystkich automatycznych sesjach autouzupełniania (gdy umieszczasz fragment lub uruchamiasz autouzupełnianie za pomocą intencji, interfejs API zrobi to automatycznie).

Pakiet SDK Places na Androida używa parametru AutocompleteSessionToken do identyfikowania każdej sesji. Aplikacja powinna przekazać nowy token sesji na początku każdej nowej sesji, a potem ten sam token wraz z identyfikatorem miejsca w kolejnych wywołaniach fetchPlace(), aby pobrać szczegóły miejsca wybranego przez użytkownika.

Więcej informacji o tokenach sesji

Ograniczanie wyników autouzupełniania

Możesz ograniczyć wyniki autouzupełniania do określonego regionu geograficznego lub odfiltrować wyniki według jednego lub większej liczby typów miejsc albo do maksymalnie 5 krajów. Możesz zastosować te ograniczenia do aktywności autouzupełniania, AutocompleteSupportFragmenti interfejsów API do automatycznego autouzupełniania.

Aby ograniczyć wyniki, wykonaj te czynności:

• Aby preferować wyniki z określonego regionu, wywołaj funkcję setLocationBias() (nadal mogą być zwracane niektóre wyniki spoza określonego regionu).
• Aby wyświetlać tylko wyniki z określonego regionu, wywołaj funkcję setLocationRestriction() (zwrócone zostaną tylko wyniki z określonego regionu).
• Aby zwrócić tylko wyniki zgodne z danym typem miejsca, wywołaj funkcję setTypesFilter() (na przykład podanie parametru TypeFilter.ADDRESS spowoduje zwrócenie tylko wyników z dokładnym adresem).
• Aby zwrócić wyniki tylko z maksymalnie 5 wybranych krajów, wywołaj funkcję setCountries(). Kraje muszą być podawane jako 2-znakowe kody krajów zgodne ze standardem ISO 3166-1 alfa-2.

Wyniki zorientowane na konkretny region

Aby zastosować filtrowanie wyników autouzupełniania do konkretnego regionu geograficznego, wywołaj funkcję setLocationBias(), podając parametr RectangularBounds. Poniższy przykład kodu pokazuje wywołanie funkcji setLocationBias() w przypadku wystąpienia fragmentu kodu, aby zastosować sugestie autouzupełniania w regionie Sydney w Australii.

    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

      

Ograniczenie wyników do konkretnego regionu

Aby ograniczyć wyniki autouzupełniania do konkretnego regionu geograficznego, wywołaj funkcję setLocationRestriction(), podając parametr RectangularBounds. Poniższy przykład kodu pokazuje wywołanie funkcji setLocationRestriction() w przypadku wystąpienia fragmentu, aby zastosować sugestie autouzupełniania w regionie Sydney w Australii.

    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

      

Uwaga: to ograniczenie dotyczy tylko całych tras. Wyniki syntetyczne znajdujące się poza granicami prostokąta mogą być zwracane na podstawie trasy, która nakłada się na ograniczenie lokalizacji.

Filtrowanie wyników według typu miejsca lub kolekcji typu

Możesz ograniczyć wyniki zapytania autouzupełniania, aby zwracały tylko określone typy miejsc. Określ filtr za pomocą typów miejsc lub kolekcji typów wymienionych w tabelach 1, 2 i 3 w sekcji Typy miejsc. Jeśli nie podasz żadnego typu, zwrócone zostaną wszystkie typy.

Aby filtrować wyniki autouzupełniania, wywołaj funkcję setTypesFilter(), aby ustawić filtr.

Aby określić filtr typu lub kolekcji typów:

• Wywołaj funkcję setTypesFilter() i określ maksymalnie 5 wartości type z tabeli 1 i tabeli 2, które są widoczne na stronie Typy miejsc. Wartości typu są zdefiniowane przez stałe w PlaceTypes.

• Wywołaj funkcję setTypesFilter() i wskaż typ kolekcji z tabeli 3 na stronie Typy miejsc. Wartości kolekcji są definiowane przez stałe w PlaceTypes.

  W żądaniu można podać tylko jeden typ z tabeli 3. Jeśli określisz wartość z tabeli 3, nie możesz określić wartości z tabeli 1 ani 2. Jeśli to zrobisz, wystąpi błąd.

W tym przykładzie kodu wywołujemy funkcję setTypesFilter() obiektu AutocompleteSupportFragment i określamy wiele wartości typu.

    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

      

    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

      

Poniższy przykład kodu pokazuje wywołanie funkcji setTypesFilter() w obiekcie AutocompleteSupportFragment w celu ustawienia filtra, który zwraca tylko wyniki z dokładnym adresem, przez określenie zbioru typu.

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

      

Poniższy przykład kodu pokazuje wywołanie funkcji setTypesFilter() w funkcji IntentBuilder w celu ustawienia filtra, który zwraca tylko wyniki z dokładnym adresem, przez określenie zbioru typu.

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

      

    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .build(this);

      

Filtrowanie wyników według kraju

Aby filtrować wyniki autouzupełniania do maksymalnie 5 krajów, wywołaj funkcję setCountries(), aby ustawić kod kraju. Następnie prześlij filtr do fragmentu lub zamiaru. Kraje muszą być przekazywane jako 2-znakowy kod kraju zgodny ze standardem ISO 3166-1 alfa-2.

Poniższy przykład kodu pokazuje wywołanie funkcji setCountries() w funkcji AutocompleteSupportFragment, aby ustawić filtr zwracający tylko wyniki z wybranych krajów.

    autocompleteFragment.setCountries("AU", "NZ")

      

    autocompleteFragment.setCountries("AU", "NZ");

      

Limity wykorzystania

Korzystanie z interfejsu Places API, w tym z pakietu Places SDK na Androida, nie jest już ograniczone do maksymalnej liczby żądań na dzień (QPD). Nadal obowiązują jednak te limity wykorzystania:

• Limit szybkości to 6000 QPM (żądań na minutę). Jest ona obliczana jako suma żądań wysyłanych po stronie klienta i po stronie serwera przez wszystkie aplikacje korzystające z danych logowania tego samego projektu.

Wyświetlanie informacji o pochodzeniu danych w aplikacji

• Jeśli aplikacja korzysta z usługi autouzupełniania za pomocą kodu, interfejs użytkownika musi wyświetlać informacje o źródle „Technologia Google” lub być widoczny na mapie z logo Google.
• Jeśli Twoja aplikacja korzysta z widżetu autouzupełniania, nie musisz podejmować żadnych dodatkowych działań (wymagana atrybucja jest wyświetlana domyślnie).
• Jeśli po uzyskaniu miejsca docelowego na podstawie identyfikatora pobierzesz i wyświetlisz dodatkowe informacje o miejscu docelowym, musisz też wyświetlić atrybuty zewnętrzne.

Więcej informacji znajdziesz w dokumentacji dotyczącej atrybucji.

Optymalizacja autouzupełniania miejsc

W tej sekcji znajdziesz sprawdzone metody, które pomogą Ci w pełni wykorzystać możliwości usługi Autouzupełnianie miejsc.

Oto kilka ogólnych wskazówek:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie: Widżetu autouzupełniania z Maps JavaScript API, Widżetu autouzupełniania z pakietu SDK Miejsc na Androida lub Widżetu autouzupełniania z pakietu SDK Miejsc na iOS.
• Na początku zaznaj się z najważniejszymi polami danych usługi Autouzupełnianie miejsc.
• Pola preferencji lokalizacji i ograniczeń lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na działanie funkcji autouzupełniania.
• Użyj obsługi błędów, aby zapewnić płynne działanie aplikacji, jeśli interfejs API zwróci błąd.
• Upewnij się, że aplikacja obsługuje przypadki, gdy nie ma wyboru, i oferuje użytkownikom sposób na kontynuowanie.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszty korzystania z usługi autouzupełniania miejsc, użyj masek pól w widżetach Szczegóły miejsca i Autouzupełnianie miejsc, aby zwracać tylko potrzebne pola z danymi o miejscach.

Zaawansowana optymalizacja kosztów

Rozważ automatyczne wdrażanie funkcji Autocomplete miejsc, aby uzyskać dostęp do cen za prośbę i wysłać wyniki interfejsu Geocoding API dotyczące wybranego miejsca zamiast Szczegółów miejsca. Cena taryfy „za żądanie” w połączeniu z interfejsem Geocoding API jest bardziej opłacalna niż taryfa „za sesję” (obejmująca poszczególne sesje) pod warunkiem spełnienia obu tych warunków:

• Jeśli interesuje Cię tylko szerokość geograficzna, długość geograficzna lub adres wybranego miejsca przez użytkownika, interfejs Geocoding API dostarczy te informacje w mniejszym stopniu niż wywołanie interfejsu PlaceDetails.
• Jeśli użytkownicy wybierają prognozę autouzupełniania w ramach średnio 4 lub mniej żądań prognozy autouzupełniania, cena za żądanie może być bardziej opłacalna niż cena za sesję.

Czy Twoja aplikacja wymaga jakichkolwiek informacji oprócz adresu i szerokości geograficznej/długości geograficznej wybranej prognozy?

Sprawdzone metody dotyczące wydajności

W tych wytycznych znajdziesz wskazówki dotyczące optymalizacji działania autouzupełniania w Google Maps:

• Dodaj ograniczenia dotyczące kraju, preferencje dotyczące lokalizacji oraz (w przypadku implementacji programowych) preferencje językowe do implementacji funkcji Autouzupełniania miejsc. W przypadku widżetów nie trzeba podawać preferencji językowych, ponieważ są one pobierane z przeglądarki lub urządzenia mobilnego użytkownika.
• Jeśli autouzupełnianie miejsc jest wyświetlane z mapą, możesz dostosować lokalizację do widoku mapy.
• Jeśli użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania, ponieważ żadna z nich nie jest pożądanym adresem, możesz ponownie użyć oryginalnego danych wejściowych użytkownika, aby uzyskać bardziej trafne wyniki:
  • Jeśli oczekujesz, że użytkownik poda tylko informacje o adresie, ponownie użyj pierwotnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
  • Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania znajdowania miejsc. Jeśli wyniki mają być uzyskiwane tylko w konkretnym regionie, użyj ustawienia lokalizacji.
  Inne scenariusze, w których warto użyć interfejsu Geocoding API:
  • Użytkownicy wpisują adresy pomieszczeń w budynku, np. adresy konkretnych lokali w budynku. Na przykład czeski adres „Stroupežnického 3191/17, Praha” daje częściową podpowiedź w autouzupełnianiu adresów.
  • Użytkownicy wpisujący adresy z prefiksami odcinków dróg, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Rozwiązywanie problemów

Chociaż może wystąpić wiele różnych błędów, większość z nich jest zwykle spowodowana błędami konfiguracji (np. użyto nieprawidłowego klucza API lub klucz API został źle skonfigurowany) lub błędami dotyczącymi limitu (aplikacja przekroczyła swój limit). Więcej informacji o limitach znajdziesz w sekcji Limity wykorzystania.

Błędy występujące podczas korzystania z kontroli autouzupełniania są zwracane w wywołaniu zwrotnym onActivityResult(). Aby uzyskać wiadomość o stanie wyniku, zadzwoń pod numer Autocomplete.getStatus().