Autouzupełnianie miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Usługa autouzupełniania w pakiecie SDK Miejsc dla Androida zwraca prognozy dotyczące miejsc w odpowiedzi na zapytania użytkowników. W miarę wpisywania tekstu przez użytkownika usługa autouzupełniania zwraca sugestie miejsc takich jak firmy, adresy, kody plus i ciekawe miejsca.

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

Dodawanie widżetu autouzupełniania

Widżet autouzupełniania to okno wyszukiwania z wbudowanym autouzupełnianiem. 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, której aplikacja może potem użyć, aby uzyskać szczegółowe informacje o wybranym miejscu.

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

Opcja 1. Umieść fragment AutocompleteSupportFragment

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

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

Dodawanie fragmentu AutocompleteSupportFragment do aktywności

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 zapewnić 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ć element onActivityResult, musisz wywołać funkcję super.onActivityResult. W przeciwnym razie fragment nie będzie działać prawidłowo.

Dodawanie detektora 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ć detektor 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. Użycie intencji do uruchomienia działania autouzupełniania

Jeśli chcesz, aby aplikacja wykorzystywała inny sposób nawigacji (np. do uruchamiania autouzupełniania za pomocą ikony, a nie pola wyszukiwania), może uruchomić autouzupełnianie za pomocą intencji.

Aby uruchomić widżet autouzupełniania za pomocą intencji, wykonaj te czynności:

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

Tworzenie intencji autouzupełniania

W poniższym przykładzie użyto właściwości 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);

Gdy uruchamiasz widżet autouzupełniania za pomocą intencji, możesz wybrać tryb nakładki lub wyświetlania pełnoekranowego. Na poniższych zrzutach ekranu widać odpowiednio poszczególne tryby wyświetlania:

W trybie nakładki widżet autouzupełniania jest nałożony na interfejs połączeń.
Rysunek 1. Widżet autouzupełniania w trybie NAKŁADKA
W trybie pełnoekranowym widżet autouzupełniania wypełnia cały ekran.
Rysunek 2. Widżet autouzupełniania w trybie pełnoekranowym

Rejestrowanie wywołania zwrotnego dla wyniku intencji

Aby otrzymywać powiadomienie, gdy użytkownik wybierze miejsce, zdefiniuj program uruchamiający registerForActivityResult(), który będzie uruchamiać działanie i obsługiwać wynik jak w przykładzie poniżej. Jeśli użytkownik wybrał prognozę, zostanie ona wyświetlona w intencji zawartej w obiekcie wyniku. Intencja została skompilowana 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 dotyczących miejsc

Jako alternatywę dla interfejsu udostępnianego przez widżet autouzupełniania możesz utworzyć niestandardowy interfejs wyszukiwania. Aplikacja musi wtedy automatycznie otrzymywać prognozy dotyczące miejsc. Aplikacja może uzyskać listę przewidywanych nazw miejsc lub adresów z interfejsu API autouzupełniania, wywołując metodę PlacesClient.findAutocompletePredictions(), przekazując obiekt FindAutocompletePredictionsRequest z tymi parametrami:

  • Wymagane: ciąg znaków query zawierający tekst wpisany przez użytkownika.
  • Zalecane: AutocompleteSessionToken, który grupuje etapy zapytania i wyboru wyszukiwania użytkownika w osobną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy się, gdy wybierze miejsce.
  • Zalecane: obiekt RectangularBounds, który określa granice szerokości i długości geograficznej w celu ograniczenia wyników do określonego regionu.
  • Opcjonalnie: co najmniej 1 dwuliterowy kod kraju (ISO 3166-1 alfa-2) wskazujący kraj lub kraje, do których należy ograniczyć wyniki.

  • Opcjonalnie: właściwość TypeFilter, za pomocą której możesz ograniczyć wyniki do określonego typu miejsca. Obsługiwane są te typy miejsc:

    • TypeFilter.GEOCODE – zwraca tylko wyniki geokodowania, a nie firm. Prośba ta służy do wskazywania wyników, 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, jeśli 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 wartości LOCALITY lub ADMINISTRATIVE_AREA_LEVEL_3.

  • Opcjonalnie: pole LatLng określające lokalizację, z której pochodzi żądanie. Gdy wywołujesz metodę setOrigin(), dla każdej prognozy autouzupełniania w odpowiedzi usługa zwraca odległość od podanego źródła (distanceMeters) od podanego źródła.

Informacje o typach miejsc znajdziesz w przewodniku po typach miejsc.

Poniższy przykład zawiera 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 Task. FindAutocompletePredictionsResponse zawiera listę obiektów AutocompletePrediction reprezentujących przewidywane miejsca. Jeśli nie istnieje znane miejsce odpowiadające zapytaniu i kryteriom filtra, lista może być pusta.

W przypadku każdego przewidywanego miejsca możesz wywołać następujące metody, aby pobrać informacje o miejscu:

  • getFullText(CharacterStyle) zwraca pełny tekst opisu miejsca. To połączenie tekstu głównego i dodatkowego. Przykład: „Wieża Eiffla, aleja Anatole'a France'a, Paryż, Francja”. Ta metoda pozwala dodatkowo wyróżnić sekcje tekstu, które pasują do wyszukiwania, z wybranym stylem, za pomocą metody CharacterStyle. Parametr CharacterStyle jest opcjonalny. Jeśli nie potrzebujesz żadnego podświetlenia, ustaw wartość null.
  • getPrimaryText(CharacterStyle) zwraca główny tekst opisujący miejsce. Jest to zwykle nazwa miejsca. Przykłady: „Wieża Eiffla” i „123 Pitt Street”.
  • getSecondaryText(CharacterStyle) zwraca tekst podmiotu zależnego opisu miejsca. Jest to przydatne na przykład jako drugi wiersz dla podpowiedzi autouzupełniania. Przykłady: „A Avenue Anatole France, Paryż, Francja” i „Sydney, Nowa Południowa Walia”.
  • getPlaceId() zwraca identyfikator przewidywanego miejsca. Identyfikator miejsca to tekstowy identyfikator, który jednoznacznie identyfikuje miejsce. Możesz go później użyć, aby ponownie pobrać obiekt Place. Więcej informacji o identyfikatorach miejsc w pakiecie SDK Miejsc na Androida znajdziesz w szczegółach dotyczących miejsc. Ogólne informacje o identyfikatorach miejsc znajdziesz w artykule Omówienie identyfikatora miejsca.
  • getPlaceTypes() zwraca listę typów miejsc powiązanych z tym miejscem.
  • getDistanceMeters() zwraca prostą odległość wyrażoną w metrach między tym miejscem a źródłem określonym w żądaniu.

Tokeny sesji

Tokeny sesji grupują fazy zapytania i wyboru autouzupełniania wyszukiwania użytkownika w oddzielną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy się, gdy wybierze miejsce. Każda sesja może zawierać kilka zapytań, a następnie wybrać jedno miejsce. Po zakończeniu sesji token straci ważność, a aplikacja musi wygenerować nowy token dla każdej sesji. Zalecamy używanie tokenów sesji we wszystkich sesjach automatycznego autouzupełniania (gdy umieścisz fragment lub uruchomisz autouzupełnianie za pomocą intencji, interfejs API zajmie się tym automatycznie).

Pakiet Places SDK na Androida używa tagu AutocompleteSessionToken do identyfikowania sesji. Aplikacja powinna przekazywać nowy token sesji przy rozpoczęciu każdej nowej sesji, a następnie przekazywać ten sam token wraz z identyfikatorem miejsca w kolejnym wywołaniu funkcji fetchPlace(), aby pobrać informacje o miejscu wybranym przez użytkownika.

Więcej informacji o tokenach sesji

Ogranicz wyniki autouzupełniania

Możesz ograniczyć wyniki autouzupełniania do określonego regionu geograficznego lub filtrować je według typów miejsc bądź typów albo maksymalnie 5 krajów. Te ograniczenia możesz zastosować do aktywności autouzupełniania, funkcji AutocompleteSupportFragment i interfejsów API automatycznego autouzupełniania.

Aby ograniczyć wyniki, wykonaj te czynności:

  • Aby preferować wyniki ze zdefiniowanego regionu, wywołaj setLocationBias() (niektóre wyniki spoza zdefiniowanego regionu mogą nadal zostać zwrócone).
  • Aby wyświetlać tylko wyniki ze wskazanego regionu, wywołaj setLocationRestriction() (zwracane będą tylko wyniki z tego regionu).
  • Aby zwrócić tylko wyniki pasujące do określonego typu miejsca, wywołaj setTypesFilter() (na przykład określenie TypeFilter.ADDRESS spowoduje zwrócenie tylko wyników z dokładnym adresem).
  • Aby zwrócić tylko wyniki z maksymalnie 5 określonych krajów, wywołaj setCountries(). Kraje muszą być przekazywane w postaci dwuznakowego kodu kraju zgodnego z ISO 3166-1 alfa-2.

Uprzedzenia wyników w konkretnym regionie

Aby uprzedzić wyniki autouzupełniania według konkretnego regionu geograficznego, wywołaj setLocationBias(), przekazując w ten sposób RectangularBounds. Poniższy przykładowy kod pokazuje wywoływanie funkcji setLocationBias() w instancji fragmentu w celu skierowania 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 określonego regionu geograficznego, wywołaj setLocationRestriction(), przekazując w ten sposób sygnał RectangularBounds. Poniższy przykładowy kod pokazuje wywoływanie funkcji setLocationRestriction() w instancji fragmentu w celu promowania sugestii autouzupełniania w regionie 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 ograniczenie dotyczące lokalizacji.

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

Możesz ograniczyć wyniki żądania autouzupełniania, tak aby zwracały tylko określony typ miejsca. Określ filtr przy użyciu 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 są wszystkie typy.

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

Aby określić filtr kolekcji typu lub typu:

  • Wywołaj funkcję setTypesFilter() i podaj maksymalnie 5 wartości type z tabel Typy miejsc z tabel 1 i 2. Wartości typu są definiowane przez stałe w PlaceTypes.

  • Wywołaj funkcję setTypesFilter() i określ zbiór typu z tabeli 3 widoczny w sekcji Typy miejsc. Wartości kolekcji są zdefiniowane przez stałe w obiekcie 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 z tabeli 2. Jeśli to zrobisz, wystąpi błąd.

Ten przykładowy kod wywołuje setTypesFilter() w AutocompleteSupportFragment i określa wiele wartości typów.

Kotlin



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

Java


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

Poniższy przykładowy kod ilustruje wywoływanie funkcji setTypesFilter() w elemencie AutocompleteSupportFragment w celu skonfigurowania filtra, który będzie zwracał tylko wyniki z dokładnym adresem przez określenie zbioru typów.

Kotlin



    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

Java


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

Poniższy przykładowy kod pokazuje wywołanie setTypesFilter() na IntentBuilder w celu ustawienia filtra, który będzie zwracał 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);

Filtruj wyniki według kraju

Jeśli chcesz przefiltrować wyniki autouzupełniania do 5 krajów, wywołaj setCountries() w celu ustawienia kodu kraju. Następnie przekaż filtr do fragmentu lub intencji. Kraje muszą być przekazywane w postaci dwuznakowego kodu kraju zgodnego z ISO 3166-1 alfa-2.

Poniższy przykładowy kod pokazuje wywołanie setCountries() na AutocompleteSupportFragment, aby 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 SDK Places na Androida, nie jest już ograniczone do maksymalnej liczby żądań dziennie (QPD). Nadal jednak obowiązują te limity wykorzystania:

  • Limit żądań na minutę to 6000 QPM (żądań na minutę). Wartość ta jest obliczana jako suma żądań po stronie klienta i po stronie serwera dla wszystkich aplikacji korzystających z danych logowania w tym samym projekcie.

Wyświetl atrybucję w swojej aplikacji

  • Jeśli aplikacja korzysta z usługi autouzupełniania automatycznie, jej interfejs musi wyświetlać informację „Technologia Google” lub znajdować się na mapie marki Google.
  • Jeśli Twoja aplikacja używa widżetu autouzupełniania, nie musisz nic robić (domyślnie wyświetlana jest wymagana atrybucja).
  • Jeśli pobierasz i wyświetlasz dodatkowe informacje o miejscu po uzyskaniu miejsca na podstawie identyfikatora, musisz też uwzględnić informacje o ich źródłach.

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

Optymalizacja miejsca autouzupełniania

W tej sekcji znajdziesz 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 na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania interfejsu Maps JavaScript API, widżetu autouzupełniania z pakietu SDK Miejsc na Androida lub widżetu autouzupełniania z pakietu SDK Miejsc na iOS elementu interfejsu użytkownika autouzupełniania
  • Od razu poznaj najważniejsze pola danych autouzupełniania miejsc.
  • Pola promowania lokalizacji i ograniczenia lokalizacji są opcjonalne, ale mogą mieć znaczny wpływ na działanie autouzupełniania.
  • Korzystaj z obsługi błędów, aby mieć pewność, że aplikacja bez problemów przestanie działać, gdy interfejs API zwróci błąd.
  • Sprawdź, czy aplikacja działa, gdy nie ma wyboru, i daje użytkownikom możliwość kontynuowania.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszt korzystania z usługi autouzupełniania, używaj masek pól w widżetach szczegółów miejsca i widżetów autouzupełniania miejsca, aby zwracać tylko potrzebne pola danych o miejscach.

Zaawansowana optymalizacja kosztów

Rozważ zautomatyzowaną implementację autouzupełniania miejsc, aby uzyskać dostęp do cen na żądanie i wysyłać żądania wyników interfejsu Geocoding API dotyczących wybranego miejsca zamiast szczegółów miejsca. Model cenowy za żądanie w połączeniu z interfejsem Geocoding API jest bardziej opłacalny niż model cenowy 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 miejsca, interfejs Geocoding API dostarcza te informacje dla mniej niż wywołania Place Details.
  • Jeśli użytkownicy wybiorą podpowiedź autouzupełniania w zakresie nie więcej niż 4 żądań podpowiedzi autouzupełniania, model cenowy za żądanie może być bardziej opłacalny niż model płatności za sesję.
Aby uzyskać pomoc w wyborze odpowiedniego wdrożenia autouzupełniania miejsc, wybierz kartę, która odpowiada Twojej odpowiedzi na to pytanie.

Czy aplikacja wymaga innych informacji poza adresem i szerokością geograficzną wybranej prognozy?

Tak, potrzebujemy więcej informacji

Korzystaj z autouzupełniania miejsc opartego na sesji, korzystając z szczegółów miejsca.
Twoja aplikacja wymaga informacji o miejscach, takich jak nazwa miejsca, status firmy lub godziny otwarcia, dlatego implementacja autouzupełniania miejsc powinna korzystać z tokenu sesji (programowego lub wbudowanego w widżety JavaScript, Androida bądź iOS.Koszt to 0,017 USD za sesję plus odpowiednie kody SKU danych miejsc w zależności od tego, o jakie pola danych miejsc prosisz.

Implementacja widżetów
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript oraz Android lub iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądania szczegółów miejsca dotyczące wybranej prognozy. Pamiętaj, by określić parametr fields, aby mieć pewność, że wysyłasz tylko żądanie pól danych o miejscu, których potrzebujesz.

Implementacja automatyzacji
W żądaniach autouzupełniania miejsc używaj tokena sesji. W żądaniu Szczegóły miejsca dotyczące wybranej prognozy podaj te parametry:

  1. identyfikator miejsca z odpowiedzi na autouzupełnianie miejsca,
  2. Token sesji używany w żądaniu autouzupełniania miejsca.
  3. Parametr fields określający potrzebne pola danych o miejscu

Nie, wymaga tylko adresu i lokalizacji

Interfejs Geocoding API może być tańszą opcją niż informacje o miejscu, w zależności od tego, jak dobrze korzystasz z autouzupełniania. Skuteczność autouzupełniania każdej aplikacji różni się w zależności od tego, co wpisują użytkownicy, gdzie aplikacja jest używana i czy wdrożone zostały sprawdzone metody dotyczące optymalizacji wydajności.

Aby odpowiedzieć na poniższe pytanie, przed wybraniem podpowiedzi autouzupełniania miejsca w aplikacji sprawdź, ile znaków średnio wpisuje użytkownik.

Czy użytkownicy wybierają podpowiedzi autouzupełniania miejsca średnio w przypadku 4 żądań lub mniejszej liczby żądań?

Tak

Zaimplementuj autouzupełnianie miejsc automatycznie bez tokenów sesji i wywołuj interfejs Geocoding API dla prognozy wybranego miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej za 0,005 USD za żądanie. Utworzenie 4 żądań typu Place Autocomplete – Per Request (Autouzupełnianie – według żądania) kosztuje 0,01132 USD, więc łączny koszt 4 żądań plus wywołania Geocoding API dla wybranej prognozy miejsca wynosi 0,01632 USD, czyli mniej niż cena autouzupełniania na sesję, która wynosi 0,017 USD za sesję1.

Zastanów się nad skorzystaniem ze sprawdzonych metod dotyczących skuteczności, aby pomóc użytkownikom uzyskać podpowiedzi, których szukają, przy użyciu jeszcze mniejszej liczby znaków.

Nie

Korzystaj z autouzupełniania miejsc opartego na sesji, korzystając z szczegółów miejsca.
Średnia liczba spodziewanych żądań, które zostaną wysłane, zanim użytkownik wybierze prognozę autouzupełniania miejsca, przekracza koszt ceny za sesję. Dlatego Twoja implementacja autouzupełniania miejsc powinna korzystać z tokenu sesji zarówno dla żądań autouzupełniania miejsc, jak i powiązanych z nimi żądań informacji o miejscach. Ich łączny koszt to 0,017 USD za sesję1.

Implementacja widżetów
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript oraz Android lub iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądania szczegółów miejsca dotyczące wybranej prognozy. Pamiętaj, by określić parametr fields, aby mieć pewność, że żądanie dotyczy tylko pól danych podstawowych.

Implementacja automatyzacji
W żądaniach autouzupełniania miejsc używaj tokena sesji. W żądaniu Szczegóły miejsca dotyczące wybranej prognozy podaj te parametry:

  1. identyfikator miejsca z odpowiedzi na autouzupełnianie miejsca,
  2. Token sesji używany w żądaniu autouzupełniania miejsca.
  3. Parametr fields określający pola Dane podstawowe, takie jak adres i geometria

Rozważ opóźnienie żądań autouzupełniania miejsc
Aby zmniejszyć liczbę żądań, możesz zastosować takie strategie jak opóźnienie żądania autouzupełniania miejsca do wpisania przez użytkownika pierwszych 3 lub 4 znaków. Na przykład wykonywanie żą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 potem wybierze prognozę, dla której utworzysz jedno żądanie do interfejsu Geocoding API, łączny koszt wyniesie 0,01632 USD (4 * 0,00283 Autouzupełniaj na żądanie + 0,005 USD za kodowanie geograficzne)1.

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań automatyzacji spadnie poniżej 4, postępuj zgodnie ze wskazówkami dotyczącymi skutecznej implementacji autouzupełniania miejsc za pomocą interfejsu Geocoding API. Pamiętaj, że opóźnienie żądań może być postrzegane jako opóźnienie przez użytkownika, który może oczekiwać podpowiedzi po każdym naciśnięciu klawisza.

Zastanów się nad skorzystaniem ze sprawdzonych metod dotyczących skuteczności, aby pomóc użytkownikom uzyskać spodziewaną prognozę przy użyciu mniejszej liczby znaków.

  1. Podane tu koszty są podane w dolarach amerykańskich. Pełne ceny znajdziesz na stronie płatności 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 automatyzacji) ustawienia języka. W przypadku widżetów preferencje językowe nie są wymagane, ponieważ wybierają one język z przeglądarki użytkownika lub urządzenia mobilnego.
  • Jeśli wraz z mapą jest wyświetlana mapa, możesz dostosować lokalizację według widocznego obszaru mapy.
  • Jeśli użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania, zwykle dlatego, że żadna z tych podpowiedzi nie odpowiada docelowemu adresowi wyniku, możesz ponownie wykorzystać dane wejściowe użytkownika, by uzyskać bardziej trafne wyniki:
    • Jeśli oczekujesz, że użytkownik wpisze tylko informacje adresowe, w wywołaniu interfejsu Geocoding API użyj tych samych danych wejściowych.
    • Jeśli spodziewasz się, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca, podając nazwę lub adres, użyj funkcji Znajdź zgłoszenie miejsca. Jeśli wyniki są oczekiwane tylko w konkretnym regionie, użyj promowania lokalizacji.
    Inne scenariusze, w których najlepiej skorzystać z interfejsu Geocoding API, to:
    • Użytkownicy podający adresy podrzędne w krajach, w których obsługa autouzupełniania miejsc w przypadku adresów podrzędnych jest niekompletna, np. w Czechach, Estonii i Litwie. Na przykład adres w języku czeskim „Stroupežnického 3191/17, Praha” generuje częściową prognozę w autouzupełnianiu miejsca.
    • Użytkownicy, którzy wpisują adresy z prefiksami fragmentu drogi, takimi jak „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Rozwiązywanie problemów

Błędy mogą być różne, ale większość z nich wynika z błędów konfiguracji (np. użycie niewłaściwego klucza interfejsu API lub jego nieprawidłowe skonfigurowanie) bądź błędy związane z limitami (aplikacja przekroczyła limit). Więcej informacji o limitach znajdziesz w sekcji Limity wykorzystania.

Błędy, które wystąpią w przypadku korzystania z elementów sterujących autouzupełniania, są zwracane w wywołaniu zwrotnym onActivityResult(). Zadzwoń pod numer Autocomplete.getStatus(), aby otrzymać komunikat o stanie wyniku.