Autouzupełnianie miejsc

Usługa autouzupełniania w pakiecie Miejsca SDK na Androida zwraca podpowiedzi w odpowiedzi na zapytania użytkowników. Gdy użytkownik wpisuje tekst, usługa autouzupełniania zwraca sugestie dotyczące miejsc takich jak firmy, adresy, kody plus i ciekawe miejsca.

Autouzupełnianie do dodawania do aplikacji jest następujące:

Dodaj widżet autouzupełniania

Widżet autouzupełniania to okno wyszukiwania z wbudowaną funkcją autouzupełniania. Gdy użytkownik wpisuje wyszukiwane hasło, widżet wyświetla listę przewidywanych miejsc do wyboru. Gdy użytkownik dokona wyboru, zwracana jest instancja Place, za pomocą której aplikacja może uzyskać informacje o wybranym miejscu.

Widżet autouzupełniania możesz dodać do aplikacji na 2 sposoby:

Opcja 1. Umieszczanie elementu AutocompleteSupportFragment

Aby dodać do aplikacji AutocompleteSupportFragment, wykonaj te czynności:

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

Dodawanie autocompleteSupportFragment do działania

Aby dodać element 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 uzyskać spójny wygląd, zagnieźdź fragment w innym elemencie układu, np. w CardView.
  • Jeśli używasz fragmentu autouzupełniania i chcesz zastąpić parametr onActivityResult, musisz wywołać metodę super.onActivityResult. W przeciwnym razie fragment nie będzie działać prawidłowo.

Dodawanie elementu PlaceSelectionListener do aktywności

PlaceSelectionListener obsługuje zwracanie miejsca w odpowiedzi na wybór użytkownika. Poniższy kod pokazuje, jak utworzyć odwołanie do fragmentu i dodać odbiornik do AutocompleteSupportFragment:

Kotlin



    // 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")
        }
    })

      

Java


    // 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. Wykorzystaj intencję do uruchomienia działania autouzupełniania

Jeśli chcesz, aby aplikacja korzystała z innego procesu nawigacyjnego (np. po to, by uruchamiać autouzupełnianie po kliknięciu ikony, a nie pola wyszukiwania), aplikacja może uruchamiać autouzupełnianie, korzystając z intencji.

Aby uruchomić widżet autouzupełniania przy użyciu intencji, wykonaj te czynności:

  1. Użyj Autocomplete.IntentBuilder, aby utworzyć intencję przekazującą wybrany tryb Autocomplete.
  2. Zdefiniuj program uruchamiający wyniki działania registerForActivityResult, który może służyć do uruchamiania intencji i obsługiwania w wyniku prognozowania miejsca wybranego przez użytkownika.

Tworzenie intencji autouzupełniania

W podanym niżej przykładzie użyto Autocomplete.IntentBuilder do utworzenia intencji uruchomienia widżetu autouzupełniania jako intencji:

Kotlin




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

      

Java



    // 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 zamierzasz uruchomić widżet autouzupełniania, możesz wybrać tryb nakładki lub wyświetlania pełnoekranowego. Na poniższych zrzutach ekranu widać odpowiednio każdy tryb wyświetlania:

W trybie nakładki widżet autouzupełniania jest nałożony na interfejs wywołania.
Rys. 1. Widżet autouzupełniania w trybie NAkładki
Podczas wyświetlania w trybie pełnoekranowym widżet autouzupełniania wypełnia cały ekran.
Rys. 2: Widżet autouzupełniania w trybie pełnoekranowym

Zarejestruj wywołanie zwrotne dla wyniku intencji

Aby otrzymać powiadomienie o wybraniu miejsca przez użytkownika, zdefiniuj program uruchamiający registerForActivityResult(), który będzie uruchamiać działanie i przetwarzać wyniki w sposób pokazany w poniższym przykładzie. Jeśli użytkownik wybrał prognozę, zostanie ona zrealizowana w intencji zawartej w obiekcie wyniku. Intencja została utworzona przez Autocomplete.IntentBuilder, więc metoda Autocomplete.getPlaceFromIntent() może wyodrębnić z niej obiekt Place.

Kotlin



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

      

Java


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

      

Automatyczne uzyskiwanie prognoz miejsc

Zamiast interfejsu użytkownika udostępnianego przez widżet autouzupełniania możesz utworzyć niestandardowy interfejs wyszukiwania. Aby to było możliwe, aplikacja musi automatycznie otrzymywać prognozy miejsc. Aplikacja może pobrać z interfejsu API autouzupełniania listę przewidywanych nazw miejsc lub adresów, wywołując metodę PlacesClient.findAutocompletePredictions(), przekazując obiekt FindAutocompletePredictionsRequest z tymi parametrami:

  • Wymagane: ciąg query zawierający tekst wpisany przez użytkownika.
  • Zalecane: AutocompleteSessionToken, który na potrzeby rozliczeń grupuje fazy zapytania i wyboru użytkownika w oddzielną sesję. Sesja zaczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy się, gdy wybiera miejsce.
  • Zalecane: obiekt RectangularBounds, który określa granice szerokości i długości geograficznej, aby ograniczać wyniki do określonego regionu.
  • Opcjonalnie: co najmniej 1 dwuliterowy kod kraju (ISO 3166-1 Alpha-2) wskazujący kraj lub kraje, do których wyniki mają zostać ograniczone.
  • Opcjonalne: TypeFilter, którego można użyć, aby ograniczyć wyniki do określonego typu miejsca. Obsługiwane są te typy miejsc:

    • TypeFilter.GEOCODE – zwraca tylko wyniki dotyczące geokodowania, a nie firmy. Użyj tego żądania, aby ujednolicić wyniki, w przypadku których określona lokalizacja może być nieokreślona.
    • TypeFilter.ADDRESS – zwraca tylko wyniki autouzupełniania z dokładnym adresem. Używaj tego typu, gdy wiesz, że użytkownik szuka w pełni określonego adresu.
    • TypeFilter.ESTABLISHMENT – zwraca tylko miejsca będące 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 hasła LOCALITY lub ADMINISTRATIVE_AREA_LEVEL_3.

  • Opcjonalne: LatLng określający lokalizację źródła żądania. Gdy wywołujesz setOrigin(), w przypadku każdej prognozy autouzupełniania w odpowiedzi usługa zwraca odległość w metrach (distanceMeters) od określonego źródła.

Informacje o typach miejsc znajdziesz w przewodniku po typach miejsc.

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

Kotlin



    // 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}")
            }
        }

      

Java


    // 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 FindAutocompletePredictionsResponse w elemencie Task. FindAutocompletePredictionsResponse zawiera listę obiektów AutocompletePrediction reprezentujących prognozowane miejsca. Lista może być pusta, jeśli nie ma znanego miejsca odpowiadającego zapytaniu i kryteriom filtra.

W przypadku każdego prognozowanego miejsca możesz wywołać te metody, aby pobrać informacje o miejscu:

  • getFullText(CharacterStyle) zwraca pełny tekst opisu miejsca. Jest to połączenie tekstu głównego i dodatkowego. Przykład: „wieża Eiffla, aleja Anatole'a France'a, Paryż, Francja”. Dodatkowo ta metoda pozwala wyróżnić sekcje opisu, które pasują do wyszukiwania i wybrany przez Ciebie styl, za pomocą właściwości CharacterStyle. Parametr CharacterStyle jest opcjonalny. Jeśli nie potrzebujesz podświetlania, ustaw wartość null.
  • getPrimaryText(CharacterStyle) zwraca główny tekst opisujący miejsce. Zwykle będzie to nazwa miejsca. Przykłady: „wieża Eiffla” i „123 Pitt Street”.
  • getSecondaryText(CharacterStyle) zwraca tekst towarzyszący opisu miejsca. Jest to przydatne np. jako drugi wiersz przy wyświetlaniu podpowiedzi autouzupełniania. Przykłady: „Aleja Anatole France, Paryż, Francja” i „Sydney, Nowa Południowa Walia”.
  • getPlaceId() zwraca identyfikator prognozowanego miejsca. Identyfikator miejsca to tekstowy identyfikator, który jednoznacznie identyfikuje miejsce, aby później ponownie pobrać obiekt Place. Więcej informacji o identyfikatorach miejsc w pakiecie SDK Miejsc na Androida znajdziesz w szczegółach Miejsc. Ogólne informacje o identyfikatorach miejsc znajdziesz w omówieniu identyfikatorów miejsc.
  • getPlaceTypes() zwraca listę typów miejsc powiązanych z tym miejscem.
  • getDistanceMeters() zwraca w metrach prostą odległość w metrach między tym miejscem a miejscem początkowym określonym w żądaniu.

Tokeny sesji

Tokeny sesji grupują fazy zapytania i wyboru użytkownika autouzupełniania wyszukiwania w oddzielną sesję na potrzeby rozliczeń. Sesja zaczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy się, gdy wybiera miejsce. Każda sesja może obejmować wiele zapytań, po których następuje wybór jednego miejsca. Po zakończeniu sesji token traci ważność. Aplikacja musi wygenerować nowy token dla każdej sesji. Zalecamy używanie tokenów sesji we wszystkich sesjach autouzupełniania zautomatyzowanych (gdy umieścisz fragment lub uruchomisz autouzupełnianie za pomocą intencji, interfejs API zrobi to automatycznie).

Pakiet SDK Miejsc na Androida używa elementu AutocompleteSessionToken do identyfikowania każdej sesji. Aplikacja powinna przekazywać nowy token sesji na początku każdej nowej sesji, a następnie przekazywać ten sam token wraz z identyfikatorem miejsca w kolejnym wywołaniu do 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 konkretnego regionu geograficznego lub filtrować je według typu miejsca lub kraju albo maksymalnie 5 krajów. Możesz zastosować te ograniczenia do aktywności autouzupełniania, funkcji AutocompleteSupportFragment i interfejsów API automatycznego autouzupełniania.

Aby ograniczyć wyniki, wykonaj te czynności:

  • Aby preferować wyniki w zdefiniowanym regionie, wywołaj setLocationBias() (niektóre wyniki spoza zdefiniowanego regionu mogą nadal być zwracane).
  • Aby wyświetlić tylko wyniki z określonego regionu, wywołaj setLocationRestriction() (zwrócone zostaną tylko wyniki ze wskazanego regionu).
  • Aby zwrócić tylko wyniki zgodne z określonym typem miejsca, wywołaj funkcję setTypesFilter() (np. określenie TypeFilter.ADDRESS spowoduje zwrócenie tylko wyników z dokładnym adresem).
  • Aby zwrócić tylko wyniki z maksymalnie 5 wybranych krajów, wywołaj funkcję setCountries(). Kraje należy przekazywać w postaci dwuznakowego kodu kraju zgodnego z normą ISO 3166-1 alfa-2.

Wyniki stronnicze w konkretnym regionie

Aby upowszechniać wyniki autouzupełniania według określonego regionu geograficznego, wywołaj setLocationBias(), przekazując wartość RectangularBounds. Poniższy przykładowy kod pokazuje wywołanie metody setLocationBias() w wystąpieniu fragmentu w celu uporządkowania sugestii autouzupełniania do regionu Sydney w Australii.

Kotlin



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

      

Java


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

      

Ograniczanie wyników do konkretnego regionu

Aby ograniczyć wyniki autouzupełniania do konkretnego regionu geograficznego, wywołaj setLocationRestriction(), przekazując RectangularBounds. Poniższy przykładowy kod pokazuje wywołanie metody setLocationRestriction() w instancji fragmentu w celu promowania sugestii autouzupełniania do regionu Sydney w Australii.

Kotlin



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

      

Java


    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 prostokątnymi granicami mogą być zwracane w przypadku trasy, która nakłada się na te ograniczenia.

Filtrowanie wyników według typów miejsc lub kolekcji typów

Możesz ograniczyć wyniki żądania autouzupełniania, aby zwracały tylko określony typ miejsca. Określ filtr, korzystając z typów miejsc lub kolekcji typów wymienionych w tabelach 1, 2 i 3 w sekcji Typy miejsc. Jeśli nic nie zostanie określone, zwracane będą wszystkie typy.

Aby filtrować wyniki autouzupełniania, wywołaj metodę setTypesFilter() w celu ustawienia filtra.

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

  • Wywołaj setTypesFilter() i określ maksymalnie pięć wartości type z tabel 1 i 2 dla typów miejsc. Wartości typu są definiowane przez stałe w PlaceTypes.

  • Wywołaj setTypesFilter() i określ zbiór typów z tabeli 3 wyświetlanej w typach miejsc. Wartości zbioru są definiowane przez stałe w elemencie PlaceTypes.

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

Ten przykładowy kod wywołuje funkcję setTypesFilter() w elemencie AutocompleteSupportFragment i określa wiele wartości typu.

Kotlin



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

      

Java


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

      

Poniższy przykładowy kod przedstawia wywoływanie funkcji setTypesFilter() w elemencie AutocompleteSupportFragment w celu ustawienia filtra, który zwraca tylko wyniki z precyzyjnym adresem przez określenie zbioru typu.

Kotlin



    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java


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

      

Poniższy przykładowy kod przedstawia wywołanie metody setTypesFilter() w elemencie IntentBuilder w celu ustawienia filtra, który zwróci tylko wyniki z dokładnym adresem przez określenie zbioru typów.

Kotlin



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

      

Java


    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 metodę setCountries() i ustaw kod kraju. Następnie zastosuj filtr do fragmentu lub intencji. Kraje należy przekazywać w postaci dwuznakowego kodu kraju zgodnego z normą ISO 3166-1 alfa-2.

Poniższy przykładowy kod pokazuje wywołanie metody setCountries() w elemencie AutocompleteSupportFragment, co pozwala ustawić filtr, który zwraca tylko wyniki z określonych krajów.

Kotlin



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

      

Java


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

      

Limity wykorzystania

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

  • Ograniczenie liczby żądań to 6000 QPM (żądania na minutę). Jest ona obliczana jako suma żądań po stronie klienta i po stronie serwera dla wszystkich aplikacji korzystających z danych logowania z tego samego projektu.

Wyświetlanie atrybucji w aplikacji

  • Jeśli aplikacja korzysta z usługi autouzupełniania w sposób zautomatyzowany, interfejs użytkownika musi wyświetlać oznaczenie „Technologia Google” lub wyświetlać się na mapie marki Google.
  • Jeśli aplikacja korzysta z widżetu autouzupełniania, nie musisz nic robić (wymagana atrybucja jest domyślnie wyświetlana).
  • Jeśli po zdobyciu miejsca według identyfikatora pobierasz i wyświetlasz dodatkowe informacje o miejscu, musisz też wyświetlać informacje o zewnętrznych atrybucjach.

Więcej informacji na ten temat znajdziesz w dokumentacji dotyczącej atrybucji.

Optymalizacja autouzupełniania miejsc

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

Oto kilka ogólnych wskazówek:

  • Najszybszym sposobem opracowania działającego interfejsu użytkownika jest użycie widżetu autouzupełniania interfejsu Maps JavaScript API, widżetu autouzupełniania w usłudze Places SDK na Androida lub elementu autouzupełniania interfejsu Places SDK dla iOS.
  • Opanuj od samego początku najważniejsze pola danych autouzupełniania miejsc.
  • Pola promowania lokalizacji i ograniczeń lokalizacji są opcjonalne, ale mogą mieć znaczny wpływ na wydajność autouzupełniania.
  • Użyj obsługi błędów, aby zapewnić płynne działanie aplikacji w przypadku zwrócenia błędu przez interfejs API.
  • Zadbaj o to, aby aplikacja działała, gdy nie ma możliwości wyboru, i umożliwiała użytkownikom 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 szczegółach miejsca, a widżety autouzupełniania miejsc zwracają tylko potrzebne pola danych miejsc.

Zaawansowana optymalizacja kosztów

Rozważ automatyczną implementację autouzupełniania miejsc, aby uzyskiwać dostęp do cen według żądania i wysyłać żądania wyników z interfejsu Geocoding API dotyczące wybranego miejsca zamiast szczegółów miejsca. Ceny za żądanie w połączeniu z interfejsem Geocoding API są bardziej opłacalne niż ceny za sesję (na podstawie sesji), jeśli spełnione są oba te warunki:

  • Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego przez użytkownika, interfejs Geocoding API dostarczy te informacje w czasie krótszym niż wywołanie Place Details.
  • Jeśli użytkownicy wybiorą podpowiedź autouzupełniania średnio w ciągu maksymalnie 4 żądań prognozy autouzupełniania, model cenowy za żądanie może być bardziej opłacalny niż model cenowy za sesję.
Aby uzyskać pomoc w wyborze implementacji autouzupełniania miejsca pasującej do Twoich potrzeb, kliknij kartę odpowiadającą Twojej odpowiedzi na to pytanie.

Czy Twoja aplikacja wymaga podania innych informacji niż adres i szerokość geograficzna wybranej prognozy?

Tak, potrzebuję więcej szczegółów

Użyj autouzupełniania miejsc na podstawie sesji z wykorzystaniem szczegółów miejsca.
Aplikacja wymaga informacji o miejscu, takich jak nazwa miejsca, status firmy lub godziny otwarcia, więc implementacja autouzupełniania miejsc powinna korzystać z tokena sesji (automatycznie lub wbudowanego w widżety JavaScript, Androida bądź iOS). Całkowity koszt to 0, 017 USD za sesję plus odpowiednie kody SKU danych miejsc w zależności od żądanych pól danych miejsc.

Implementacja widżetów
Zarządzanie sesjami jest automatycznie wbudowane w widżety
JavaScript oraz Androida i iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądanie informacji o miejscu w przypadku wybranej prognozy. Pamiętaj o określeniu parametru fields, aby mieć pewność, że wysyłasz tylko te pola danych miejsc, których potrzebujesz.

Implementacja automatyczna
W przypadku żądań autouzupełniania miejsc używaj tokena sesji. Wysyłając żądanie informacji o miejscu dla wybranej prognozy, podaj te parametry:

  1. identyfikator miejsca z odpowiedzi autouzupełniania miejsc,
  2. Token sesji używany w żądaniu autouzupełniania miejsca.
  3. Parametr fields określający pola danych miejsc, których potrzebujesz.

Nie, potrzebna jest tylko lokalizacja i adres

Interfejs Geocoding API może być tańszy niż w przypadku aplikacji Szczegóły miejsca, w zależności od wydajności korzystania z funkcji autouzupełniania. Skuteczność autouzupełniania poszczególnych aplikacji różni się w zależności od tego, co wpisują użytkownicy, gdzie dana aplikacja jest używana i czy wdrożono sprawdzone metody optymalizacji wydajności.

Aby odpowiedzieć na to pytanie, sprawdź, ile znaków średnio wpisuje użytkownik, zanim wybierzesz podpowiedź autouzupełniania miejsca w aplikacji.

Czy użytkownicy wybierają średnio 4 podpowiedzi autouzupełniania miejsca w maksymalnie 4 żądaniach?

Tak

Zaimplementuj autouzupełnianie miejsc automatycznie bez tokenów sesji i wywołaj interfejs Geocoding API dla wybranej prognozy miejsca.
Geocoding API dostarcza adresów i współrzędnych szerokości i długości geograficznej za 0,005 USD za każde żądanie. Wykonanie czterech żądań autouzupełniania miejsc – na żądanie kosztuje 0,01132 USD, więc łączny koszt 4 żądań i wywołania Geocoding API dla prognozy wybranego miejsca wynosi 0,01632 USD, czyli mniej niż 0,017 USD za sesję, czyli 0,017 USD za sesję1.

Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby użytkownicy mogli wyświetlać oczekiwane przez nich podpowiedzi przy użyciu jeszcze mniejszej liczby znaków.

Nie

Użyj autouzupełniania miejsc na podstawie sesji z wykorzystaniem szczegółów miejsca.
Ze względu na to, że średnia liczba żądań, które spodziewasz się wysłać przed wybraniem prognozy autouzupełniania miejsca przez użytkownika, przekracza koszt na sesję, dlatego Twoja implementacja autouzupełniania miejsc powinna używać tokena sesji zarówno w przypadku żądań autouzupełniania miejsc, jak i powiązanych z nimi żądania szczegółów miejsca.Łączny koszt wynosi 0,017 za sesję1.

Implementacja widżetów
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript oraz Androida i iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądanie informacji o miejscu w przypadku wybranej prognozy. Określ parametr fields, by mieć pewność, że wysyłasz tylko żądania danych podstawowych.

Implementacja automatyczna
W przypadku żądań autouzupełniania miejsc używaj tokena sesji. Wysyłając żądanie informacji o miejscu dla wybranej prognozy, podaj te parametry:

  1. identyfikator miejsca z odpowiedzi autouzupełniania miejsc,
  2. Token sesji używany w żądaniu autouzupełniania miejsca.
  3. Parametr fields określający pola danych podstawowych, takich jak adres i geometria

Rozważ opóźnianie żądań autouzupełniania miejsc
Możesz na przykład opóźnić żądanie autouzupełniania miejsca do momentu, w którym użytkownik wpisze pierwsze 3–4 znaki. Dzięki temu aplikacja będzie wysyłać mniej żądań. Na przykład wysyłanie żądań autouzupełniania miejsc dla każdego znaku po wpisaniu trzeciego znaku przez użytkownika oznacza, że jeśli użytkownik wpisze 7 znaków, a następnie wybierze prognozę, dla której utworzysz jedno żądanie do interfejsu Geocoding API, łączny koszt wyniesie 0,01632 USD (4 * 0,00283 USD za autouzupełnianie na żądanie + 0,005 geokodowania)1.

Jeśli opóźnione żądania pozwalają uzyskać średnią wartość żądania zautomatyzowanego poniżej 4, postępuj zgodnie ze wskazówkami dotyczącymi implementacji wydajnego autouzupełniania miejsc z użyciem interfejsu Geocoding API. Pamiętaj, że żądania opóźnione mogą być postrzegane jako czas oczekiwania dla użytkowników, którzy mogą oczekiwać podpowiedzi po każdym naciśnięciu klawisza.

Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby użytkownicy mogli otrzymywać oczekiwane przez nich prognozy w mniejszej liczbie znaków.


  1. Wymienione tutaj koszty są podane w dolarach amerykańskich. Pełne informacje o cenach znajdziesz na stronie Rozliczenia za Google Maps Platform.

Sprawdzone metody zwiększania skuteczności

Poniższe wskazówki opisują sposoby optymalizacji skuteczności autouzupełniania miejsc:

  • Dodaj do implementacji autouzupełniania miejsc ograniczenia związane z krajem, promowaniem lokalizacji i (w przypadku implementacji automatycznej) ustawienia języka. Preferencje językowe nie są potrzebne w przypadku widżetów, ponieważ określają one język w przeglądarce lub na urządzeniu mobilnym użytkownika.
  • Jeśli autouzupełnianiem miejsc towarzyszy mapa, możesz odchylać lokalizację według widocznego obszaru mapy.
  • Jeśli użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania (zwykle nie jest to adres pożądanego adresu), możesz ponownie użyć pierwotnych danych wejściowych użytkownika, aby uzyskać trafniejsze wyniki:
    • Jeśli oczekujesz, że użytkownik będzie wpisywać tylko informacje adresowe, użyj tych samych danych w wywołaniu interfejsu Geocoding API.
    • Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca, wpisując jego nazwę lub adres, skorzystaj z prośby o znajdowanie miejsca. Jeśli wyniki są oczekiwane tylko w konkretnym regionie, użyj promowania lokalizacji.
    Inne sytuacje, w których warto wrócić do interfejsu Geocoding API, to m.in.:
    • Użytkownicy wpisują adresy podrzędne w krajach, w których autouzupełnianie miejsc nie obsługuje adresów podrzędnych, np. w Czechach, Estonii i Litwie. Na przykład czeski adres „Stroupežnického 3191/17, Praha” generuje częściowe podpowiedzi w ramach autouzupełniania miejsc.
    • Użytkownicy, którzy wpisują adresy z prefiksem segmentu drogi, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawai'i.

Rozwiązywanie problemów

Błędy mogą być bardzo zróżnicowane, jednak większość z nich wynika z błędów konfiguracji (np. użycia niewłaściwego klucza interfejsu API lub nieprawidłowo skonfigurowanego klucza interfejsu API) lub błędów limitu (aplikacja przekroczyła limit). Więcej informacji o limitach znajdziesz w sekcji Limity wykorzystania.

Błędy występujące podczas korzystania z elementów sterujących autouzupełniania są zwracane w wywołaniu zwrotnym onActivityResult(). Wywołaj Autocomplete.getStatus(), aby otrzymać komunikat o stanie wyniku.