Autouzupełnianie miejsc

Usługa autouzupełniania w pakiecie Miejsca SDK na Androida zwraca prognozy 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 w aplikacji możesz włączyć na kilka sposobów:

• Dodaj widżet autouzupełniania, aby zaoszczędzić czas podczas programowania i zapewnić spójne wrażenia użytkownika.
• Automatyczne pobieranie prognoz miejsc w celu spersonalizowania środowiska użytkownika.

Dodaj widżet autouzupełniania

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

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

• Opcja 1. Umieść AutocompleteSupportFragment.
• Opcja 2. Uruchom działanie autouzupełniania przez intencję.

Opcja 1. Umieszczanie elementu 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 autocompleteSupportFragment do działania

Aby dodać obiekt 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, umieść fragment w innym elemencie układu, np. w CardView.
• Jeśli używasz fragmentu autouzupełniania i chcesz zastąpić właściwość 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 elementu AutocompleteSupportFragment:

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

      

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

      

Opcja 2. Użyj intencji, aby uruchomić działanie autouzupełniania

Jeśli chcesz, aby aplikacja korzystała z innego sposobu nawigacji (np. po to, by uruchamiać autouzupełnianie z poziomu ikony, a nie pola wyszukiwania), aplikacja może uruchomić tę funkcję za pomocą 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ą odpowiedni tryb Autocomplete.
2. Zdefiniuj program uruchamiający wyniki działania registerForActivityResult, którego można użyć do uruchamiania intencji i obsługiwać w wyniku przewidywanego miejsca wybranego przez użytkownika.

Tworzenie intencji autouzupełniania

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

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

      

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

      

Jeśli chcesz uruchomić widżet autouzupełniania, możesz wybrać tryb nakładki lub trybu pełnoekranowego. Poniższe zrzuty ekranu przedstawiają każdy z trybów wyświetlania:

Zarejestruj wywołanie zwrotne dla wyniku intencji

Aby otrzymać powiadomienie o wybraniu miejsca, zdefiniuj program uruchamiający registerForActivityResult(), który uruchamia działanie i obsługuje wynik w sposób pokazany poniżej. Jeśli użytkownik wybierze prognozę, zostanie ona dostarczona w intencji zawartej w obiekcie wynikowym. Intencja została skompilowana przez Autocomplete.IntentBuilder, więc metoda Autocomplete.getPlaceFromIntent() może wyodrębnić z niej obiekt Place.

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

      

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

      

Automatyczne uzyskiwanie prognoz dotyczących miejsc

Jako alternatywę dla interfejsu udostępnianego przez widżet autouzupełniania możesz utworzyć niestandardowy interfejs wyszukiwania. Aby było to możliwe, aplikacja musi automatycznie uzyskiwać prognozy miejsc. Aplikacja może pobrać 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 query zawierający tekst wpisany przez użytkownika.
• Zalecane: element AutocompleteSessionToken, który grupuje fazy zapytania i wyboru 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.
• 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ą być ograniczone.

• Opcjonalne: TypeFilter, którego możesz użyć, aby ograniczyć wyniki do określonego typu miejsca. Obsługiwane są następujące typy miejsc:

  • TypeFilter.GEOCODE – zwraca tylko wyniki geokodowania, a nie firmy. Dzięki temu żądaniu można ujednolicić wyniki, w przypadku których określona lokalizacja może być nieokreślona.
  • TypeFilter.ADDRESS – zwraca tylko wyniki autouzupełniania z precyzyjnym adresem. Użyj tego typu, gdy wiesz, że użytkownik szuka w pełni konkretnego 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 LOCALITY lub ADMINISTRATIVE_AREA_LEVEL_3.

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

Informacje o typach miejsc znajdziesz w przewodniku po typach miejsc.

Przykład poniżej pokazuje pełne wywołanie metody 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()).
    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());
        }
    });

      

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

      

Interfejs API zwraca FindAutocompletePredictionsResponse w Task. FindAutocompletePredictionsResponse zawiera listę obiektów AutocompletePrediction reprezentujących przewidywane miejsca. Jeśli zapytanie i kryteria filtra nie odpowiadają żadnemu znanemu miejscu, lista może być pusta.

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

• 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 za pomocą wybranego stylu za pomocą właściwości CharacterStyle. Parametr CharacterStyle jest opcjonalny. Jeśli nie potrzebujesz wyróżniania, ustaw wartość null.
• getPrimaryText(CharacterStyle) zwraca główny tekst opisujący miejsce. Zwykle jest to nazwa miejsca. Przykłady: „Wieża Eiffla” i „123 Pitt Street”.
• getSecondaryText(CharacterStyle) zwraca tekst pomocniczy opisu miejsca. Jest to przydatne na przykład 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 identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Dzięki temu można później ponownie pobrać obiekt Place. Więcej informacji o identyfikatorach miejsc w pakiecie Places SDK na Androida znajdziesz w artykule Place Details (Szczegóły dotyczące miejsca). 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 odległość w prostej linii 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 płatności. Sesja rozpoczyna 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 automatycznych sesjach autouzupełniania (gdy umieścisz fragment lub uruchomisz autouzupełnianie za pomocą intencji, interfejs API zrobi to automatycznie).

Pakiet Miejsca SDK na Androida używa tagu AutocompleteSessionToken do identyfikowania każdej sesji. Na początku każdej nowej sesji aplikacja powinna przekazywać nowy token sesji. Następnie w kolejnym wywołaniu do fetchPlace() przekazuje ten sam token razem z identyfikatorem miejsca, 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 i/lub przefiltrować wyniki do jednego lub kilku typów miejsca bądź do maksymalnie 5 krajów. Możesz zastosować te ograniczenia do aktywności autouzupełniania, 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 nadal mogą być zwracane).
• Aby wyświetlić tylko wyniki w zdefiniowanym regionie, wywołaj metodę setLocationRestriction() (zwrócone zostaną tylko wyniki ze wskazanego regionu).
• Aby zwrócić tylko wyniki zgodne z określonym typem miejsca, wywołaj funkcję setTypesFilter() (na przykład wpisanie TypeFilter.ADDRESS spowoduje zwrócenie tylko wyników z precyzyjnym adresem).
• Aby zwrócić tylko wyniki z maksymalnie 5 określonych krajów, wywołaj funkcję setCountries(). Kraje należy przekazywać w postaci kodu kraju zgodnego z normą ISO 3166-1 alfa-2.

Wyniki stronnicze wobec określonego regionu

Aby odchylić wyniki autouzupełniania do określonego regionu geograficznego, wywołaj setLocationBias(), przekazując RectangularBounds. Poniższy przykładowy kod przedstawia wywołanie metody setLocationBias() w instancji fragmentu w celu promowania wyników autouzupełniania w regionie Sydney w Australii.

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

      

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

      

Ograniczanie wyników do określonego regionu

Aby ograniczyć wyniki autouzupełniania do określonego regionu geograficznego, wywołaj setLocationRestriction(), przekazując RectangularBounds. Poniższy przykład kodu przedstawia wywołanie metody setLocationRestriction() w instancji fragmentu w celu odchylenia sugestii autouzupełniania do regionu Sydney w Australii.

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

      

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

      

Uwaga: to ograniczenie dotyczy tylko całych tras. Wyniki syntetyczne spoza prostokątnych granic mogą być zwracane w przypadku tras, które pokrywają się z tymi ograniczeniami.

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

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

Aby filtrować wyniki autouzupełniania, wywołaj metodę setTypesFilter() i ustaw filtr.

Aby określić typ lub filtr kolekcji typu:

• Wywołaj setTypesFilter() i podaj maksymalnie 5 wartości type z tabel 1 i 2 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 widocznej w typach miejsc. Wartości zbioru są zdefiniowane przez stałe w 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 metodę setTypesFilter() w AutocompleteSupportFragment i określa wiele wartości typów.

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

      

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

      

Poniższy przykładowy kod przedstawia wywołanie setTypesFilter() w AutocompleteSupportFragment, aby ustawić filtr, który zwraca tylko wyniki z dokładnym adresem przez określenie zbioru typu.

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

      

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Poniższy przykładowy kod przedstawia wywołanie funkcji setTypesFilter() w IntentBuilder, aby ustawić filtr, który zwraca tylko wyniki z dokładnym adresem przez określenie zbioru typu.

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

      

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(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 przekaż filtr do fragmentu lub intencji. Kraje należy przekazywać w postaci dwuznakowego kodu kraju zgodnego ze standardem ISO 3166-1 Alpha-2.

Poniższy przykładowy kod przedstawia wywołanie metody setCountries() w elemencie AutocompleteSupportFragment, aby ustawić filtr zwracający tylko wyniki z określonych krajów.

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

      

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

      

Limity wykorzystania

Korzystanie z interfejsu Miejsca API, w tym z pakietu Miejsca SDK na 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 przy użyciu danych logowania w tym samym projekcie.

Wyświetlanie atrybucji w aplikacji

• Jeśli Twoja aplikacja automatycznie korzysta z usługi autouzupełniania, interfejs użytkownika musi wyświetlać informację „Technologia Google” lub pojawiać się na mapie z logo Google.
• Jeśli aplikacja korzysta z widżetu autouzupełniania, nie musisz nic robić (wymagane informacje o atrybucji są wyświetlane domyślnie).
• Jeśli po uzyskaniu miejsca za pomocą identyfikatora pobierasz i wyświetlasz dodatkowe informacje o miejscu, musisz też wyświetlać informacje o atrybucji pochodzące od firm zewnętrznych.

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 na opracowanie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania interfejsu Maps JavaScript API, widżetu autouzupełniania w pakiecie Miejsca SDK na Androida lub elementu autouzupełniania w interfejsie pakietu Miejsca SDK na iOS.
• Opanuj od razu najważniejsze pola danych autouzupełniania miejsc.
• Pola odchyleń dotyczących lokalizacji i ograniczeń dotyczących lokalizacji są opcjonalne, ale mogą mieć znaczny wpływ na działanie autouzupełniania.
• Skorzystaj z obsługi błędów, by zapewnić płynne działanie aplikacji, gdy interfejs API zwróci błąd.
• Zadbaj o to, aby aplikacja obsługiwała aplikację, gdy nie ma możliwości wyboru, i umożliwiała użytkownikom kontynuowanie pracy.

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 danych miejsc.

Zaawansowana optymalizacja kosztów

Rozważ automatyczną implementację autouzupełniania miejsc, aby mieć dostęp do oceny według żądania i wysyłać prośby o wyniki interfejsu Geocoding API dotyczące wybranego miejsca, a nie szczegółów miejsca. Ceny za żądanie w połączeniu z interfejsem Geocoding API są bardziej opłacalne niż model cenowy na sesję (na podstawie sesji), jeśli są spełnione oba poniższe warunki:

• Jeśli potrzebujesz tylko szerokości/długości geograficznej lub adresu wybranego miejsca przez użytkownika, interfejs Geocoding API dostarcza te informacje dla mniej niż wywołania Place Details.
• Jeśli użytkownicy wybiorą prognozę autouzupełniania średnio w ciągu maksymalnie 4 żądań podpowiedzi autouzupełniania, cena za żądanie może być bardziej opłacalna niż stawka za sesję.

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

Sprawdzone metody

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

• Dodaj do implementacji autouzupełniania miejsca ograniczenia związane z krajem, promowaniem lokalizacji i (w przypadku implementacji zautomatyzowanych) ustawienia języka. Widżety nie wymagają wyboru języka, ponieważ ustawienia języka są wybierane w przeglądarce i na urządzeniu mobilnym użytkownika.
• Jeśli autouzupełnianiem miejsc towarzyszy mapa, możesz orientować lokalizację w zależności od widocznego obszaru mapy.
• W sytuacjach, gdy użytkownik nie wybierze jednej z podpowiedzi autouzupełniania (zwykle jest to spowodowane tym, że żadne z nich nie jest pożądanym adresem wyniku), możesz użyć oryginalnych danych wejściowych użytkownika, aby uzyskać trafniejsze wyniki:
  • Jeśli oczekujesz, że użytkownik będzie podawać tylko informacje adresowe, w wywołaniu Geocoding API użyj tych samych danych.
  • Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca, podając jego nazwę lub adres, skorzystaj z funkcji Znajdź prośbę o miejsce. Jeśli wyniki są oczekiwane tylko w określonym regionie, użyj promowania lokalizacji.
  Inne scenariusze, w których warto wrócić do interfejsu Geocoding API:
  • Użytkownicy wpisujący 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” zwraca częściową prognozę miejsca w autouzupełnianiu miejsc.
  • Użytkownicy wpisują adresy z prefiksem segmentu drogi, takim jak „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha, Kaneohe” na wyspie Kauai na Hawai'i.

Rozwiązywanie problemów

Chociaż może wystąpić wiele różnych błędów, większość z nich jest prawdopodobnie spowodowanych przez błędy konfiguracji (np. użycie niewłaściwego klucza interfejsu API lub nieprawidłowe skonfigurowanie klucza interfejsu API) lub błędy w limitach (aplikacja przekroczyła limit). Więcej informacji o limitach znajdziesz w artykule 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 poznać komunikat o stanie wyniku.