Il servizio di completamento automatico nell'SDK Places per Android restituisce previsioni sui luoghi in risposta alle query di ricerca degli utenti. Man mano che l'utente digita, il servizio di completamento automatico restituisce suggerimenti per luoghi come attività, indirizzi, plus code e punti di interesse.
Puoi aggiungere il completamento automatico all'app nei seguenti modi:
- Aggiungi un widget di completamento automatico per risparmiare tempo di sviluppo e garantire un'esperienza utente coerente.
- Ottieni le previsioni dei luoghi in modo programmatico per creare un'esperienza utente personalizzata.
Aggiungere un widget di completamento automatico
Il widget del completamento automatico è una finestra di dialogo di ricerca con funzionalità di completamento automatico
integrate. Quando un utente inserisce termini di ricerca, il widget presenta un elenco di luoghi previsti tra cui scegliere. Quando l'utente effettua una selezione, viene restituita un'istanza Place, che la tua app può utilizzare per ottenere dettagli sul luogo selezionato.
Sono disponibili due opzioni per aggiungere il widget del completamento automatico alla tua app:
- Opzione 1: incorpora un
AutocompleteSupportFragment. - Opzione 2: utilizza un intent per avviare l'attività di completamento automatico.
Opzione 1: incorpora un supporto per il completamento automatico
Per aggiungere un AutocompleteSupportFragment alla tua app, procedi nel seguente modo:
- Aggiungi un frammento al layout XML della tua attività.
- Aggiungi un listener alle tue attività o ai tuoi frammenti.
Aggiungi AutocompleteSupportFragment a un'attività
Per aggiungere AutocompleteSupportFragment a un'attività, aggiungi un nuovo frammento in un layout XML. Ad esempio:
<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"
/>
- Per impostazione predefinita, il frammento non ha bordo o sfondo. Per offrire un aspetto visivo coerente, nidifica il frammento all'interno di un altro elemento di layout, ad esempio CardView.
- Se utilizzi il frammento di completamento automatico e devi sostituire
onActivityResult, devi chiamaresuper.onActivityResult, altrimenti il frammento non funzionerà correttamente.
Aggiungi un PlaceSelection listener a un'attività
PlaceSelectionListener gestisce la restituzione di un luogo in risposta alla selezione dell'utente. Il codice seguente mostra la creazione di un riferimento al frammento e l'aggiunta di un listener al tuo AutocompleteSupportFragment:
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);
}
});
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")
}
})
Opzione 2: utilizza un intent per avviare l'attività di completamento automatico
Se vuoi che la tua app utilizzi un flusso di navigazione diverso (ad esempio per attivare l'esperienza di completamento automatico da un'icona anziché da un campo di ricerca), puoi avviare il completamento automatico utilizzando un intent.
Per avviare il widget di completamento automatico utilizzando un intent, procedi nel seguente modo:
- Utilizza
Autocomplete.IntentBuilderper creare un intent, passando la modalitàAutocompletedesiderata. - Definisci un lanciatore dei risultati di attività
registerForActivityResultche può essere utilizzato per avviare l'intent e gestire la previsione del luogo selezionato dell'utente nel risultato.
Creare un intent di completamento automatico
L'esempio seguente utilizza
Autocomplete.IntentBuilder
per creare un intent per avviare il widget di completamento automatico come 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);
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)
Quando utilizzi un intent per avviare il widget di completamento automatico, puoi scegliere tra le modalità di visualizzazione overlay o a schermo intero. I seguenti screenshot mostrano rispettivamente ogni modalità di visualizzazione:
Registra un callback per il risultato dell'intent
Per ricevere una notifica quando l'utente ha selezionato un luogo, definisci un Avvio app registerForActivityResult(), che avvia l'attività e gestisce anche il risultato come mostrato nell'esempio seguente. Se l'utente ha selezionato una previsione, verrà fornita nell'intent contenuto nell'oggetto risultato. Poiché l'intent è stato creato da Autocomplete.IntentBuilder, il metodo Autocomplete.getPlaceFromIntent() può estrarre l'oggetto Place.
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");
}
});
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")
}
}
Ottenere le previsioni dei luoghi in modo programmatico
Puoi creare un'interfaccia utente di ricerca personalizzata in alternativa all'interfaccia utente fornita dal widget di completamento automatico. A questo scopo, l'app deve ottenere le previsioni dei luoghi in modo programmatico. La tua app può ottenere un elenco di nomi di luoghi e/o indirizzi previsti dall'API Autocomplete chiamando PlacesClient.findAutocompletePredictions(), passando un oggetto FindAutocompletePredictionsRequest con i seguenti parametri:
- Obbligatorio: una stringa
querycontenente il testo digitato dall'utente. - Consigliato: un
AutocompleteSessionToken, che raggruppa le fasi di query e selezione di una ricerca dell'utente in una sessione discreta ai fini della fatturazione. La sessione inizia quando l'utente inizia a digitare una query e termina quando seleziona un luogo. - Consigliato:un oggetto
RectangularBounds, che specifica i limiti di latitudine e longitudine per limitare i risultati all'area geografica specificata. - Facoltativo: uno o più codici paese (ISO 3166-1 Alfa-2) di due lettere, che indicano il paese o i paesi a cui limitare i risultati.
(Facoltativo) Una
TypeFilterche puoi utilizzare per limitare i risultati al tipo di luogo specificato. Sono supportati i seguenti tipi di luoghi:TypeFilter.GEOCODE: restituisce solo risultati di geocodifica, anziché attività. Utilizza questa richiesta per disambiguare i risultati in cui la località specificata potrebbe essere indeterminata.TypeFilter.ADDRESS: restituisce solo i risultati del completamento automatico con un indirizzo preciso. Utilizza questo tipo quando sai che l'utente sta cercando un indirizzo completamente specificato.TypeFilter.ESTABLISHMENT: restituisce solo i luoghi commerciali.TypeFilter.REGIONS: restituisce solo i luoghi che corrispondono a uno dei seguenti tipi:LOCALITYSUBLOCALITYPOSTAL_CODECOUNTRYADMINISTRATIVE_AREA_LEVEL_1ADMINISTRATIVE_AREA_LEVEL_2TypeFilter.CITIES: restituisce solo i risultati che corrispondono aLOCALITYoADMINISTRATIVE_AREA_LEVEL_3.
Facoltativo: un
LatLngche specifica la posizione di origine della richiesta. Quando chiamisetOrigin(), il servizio restituisce la distanza in metri (distanceMeters) dall'origine specificata, per ogni previsione di completamento automatico nella risposta.
Per informazioni sui tipi di luoghi, consulta la guida ai tipi di luogo.
L'esempio seguente mostra una chiamata completa a
PlacesClient.findAutocompletePredictions().
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());
}
});
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}")
}
}
L'API restituisce
FindAutocompletePredictionsResponse
in un
Task. FindAutocompletePredictionsResponse contiene un elenco di oggetti AutocompletePrediction che rappresentano i luoghi previsti. L'elenco potrebbe essere vuoto se non esiste un luogo noto corrispondente alla query e ai criteri di filtro.
Per ogni luogo previsto, puoi chiamare i seguenti metodi per recuperare i dettagli del luogo:
getFullText(CharacterStyle)restituisce il testo completo della descrizione di un luogo. Questa è una combinazione del testo principale e secondario. Esempio: "Torre Eiffel, Avenue Anatole France, Parigi, Francia". Inoltre, questo metodo ti consente di evidenziare le sezioni della descrizione che corrispondono alla ricerca con uno stile a tua scelta, utilizzandoCharacterStyle. Il parametroCharacterStyleè facoltativo. Impostalo su null se non hai bisogno di evidenziare.getPrimaryText(CharacterStyle)restituisce il testo principale che descrive un luogo. Questo è di solito il nome del luogo. Esempi: "La Torre Eiffel" e "123 Pitt Street".getSecondaryText(CharacterStyle)restituisce il testo secondario della descrizione di un luogo. Ciò è utile, ad esempio, come seconda riga durante la visualizzazione delle previsioni di completamento automatico. Esempi: "Avenue Anatole France, Paris, Francia" e "Sydney, Nuovo Galles del Sud".getPlaceId()restituisce l'ID del luogo previsto. Un ID luogo è un identificatore di testo che identifica in modo univoco un luogo e che può essere utilizzato per recuperare l'oggettoPlacein un secondo momento. Per ulteriori informazioni sugli ID luogo nell'SDK Places per Android, consulta i dettagli del luogo. Per informazioni generali sugli ID luogo, consulta la panoramica sull'ID luogo.getPlaceTypes()restituisce l'elenco dei tipi di luogo associati a questo luogo.getDistanceMeters()restituisce la distanza in linea retta in metri tra questo luogo e l'origine specificata nella richiesta.
Token di sessione
I token di sessione raggruppano le fasi di query e selezione di una ricerca con completamento automatico utente in una sessione discreta ai fini della fatturazione. La sessione inizia quando l'utente inizia a digitare una query e termina quando seleziona un luogo. Ogni sessione può avere più query, seguite da una selezione del luogo. Una volta concluso una sessione, il token non è più valido; la tua app deve generare un nuovo token per ogni sessione. Consigliamo di utilizzare i token di sessione per tutte le sessioni di completamento automatico programmatico (se incorpori un frammento o avvii il completamento automatico utilizzando un intent, l'API si occupa automaticamente di questo problema).
L'SDK Places per Android utilizza una
AutocompleteSessionToken
per identificare ogni sessione. L'app deve passare un nuovo token di sessione all'inizio di ogni nuova sessione e poi trasmettere lo stesso token, insieme a un ID luogo, nella chiamata successiva a fetchPlace() per recuperare i dettagli del luogo per il luogo selezionato dall'utente.
Scopri di più sui token di sessione.
Limita i risultati del completamento automatico
Puoi limitare i risultati del completamento automatico a una regione geografica specifica e/o
filtrarli in base a uno o più tipi di luogo o fino a cinque paesi. Puoi applicare questi vincoli all'attività di completamento automatico, alle AutocompleteSupportFragment e alle API di completamento automatico programmatico.
Per limitare i risultati:
- Per preferisci i risultati all'interno dell'area geografica definita, chiama
setLocationBias()(alcuni risultati all'esterno dell'area geografica definita potrebbero essere comunque restituiti). - Per mostrare solo i risultati all'interno della regione definita, chiama
setLocationRestriction()(verranno restituiti solo i risultati all'interno della regione definita). - Per restituire solo i risultati che corrispondono a un determinato tipo di luogo, chiama
setTypesFilter()(ad esempio, specificandoTypeFilter.ADDRESS, restituisci solo i risultati con un indirizzo preciso). - Per restituire solo risultati entro un massimo di cinque paesi specificati, chiama
setCountries(). I paesi devono essere trasmessi come codice paese compatibile con lo standard ISO 3166-1 Alpha-2.
Risultati del bias per una regione specifica
Per polarizzare i risultati del completamento automatico a un'area geografica specifica, chiama
setLocationBias() e trasmetti un
RectangularBounds.
L'esempio di codice riportato di seguito mostra come chiamare setLocationBias() su un'istanza di frammento per polarizzare i suggerimenti di completamento automatico in una regione di Sydney, Australia.
Java
autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596)));
Kotlin
autocompleteFragment.setLocationBias(
RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
LatLng(-33.858754, 151.229596)
)
)
Limita i risultati a un'area geografica specifica
Per limitare i risultati del completamento automatico a un'area geografica specifica, chiama
setLocationRestriction(), trasmettendo un
RectangularBounds.
L'esempio di codice riportato di seguito mostra la chiamata a setLocationRestriction() su un'istanza di frammento per polarizzare i suggerimenti di completamento automatico in una regione di Sydney, Australia.
Java
autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596)));
Kotlin
autocompleteFragment.setLocationRestriction(
RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
LatLng(-33.858754, 151.229596)
)
)
Nota: questa limitazione si applica solo a interi percorsi. I risultati sintetici che si trovano al di fuori dei limiti rettangolari possono essere restituiti in base a una route che si sovrappone alla limitazione di località.
Filtra i risultati per tipo di luogo o raccolta dei tipi
Puoi limitare i risultati di una richiesta di completamento automatico in modo che restituiscano solo un certo tipo di luogo. Specifica un filtro utilizzando i tipi di luogo o una raccolta di tipi elencati nelle tabelle 1, 2 e 3 in Tipi di luogo. Se non viene specificato nulla, vengono restituiti tutti i tipi.
Per filtrare i risultati del completamento automatico, chiama
setTypesFilter()
per impostare il filtro.
Per specificare un tipo o un filtro di raccolta dei tipi:
Richiama
setTypesFilter()e specifica fino a cinque valori type dalla Tabella 1 e dalla Tabella 2 mostrati in Tipi di luogo. I valori del tipo sono definiti dalle costanti in PlaceTypes.Chiama
setTypesFilter()e specifica una raccolta di tipi dalla Tabella 3 visualizzata in Tipi di luogo. I valori della raccolta sono definiti dalle costanti in PlaceTypes.Nella richiesta è consentito un solo tipo dalla tabella 3. Se specifichi un valore dalla Tabella 3, non puoi specificarlo dalla Tabella 1 o dalla Tabella 2. In caso affermativo, si verifica un errore.
Il seguente esempio di codice chiama setTypesFilter() su un
AutocompleteSupportFragment e specifica più valori di tipo.
Java
autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));
Kotlin
autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))
L'esempio di codice riportato di seguito mostra la chiamata a setTypesFilter() su un
AutocompleteSupportFragment per impostare un filtro che restituisca solo i risultati con un
indirizzo preciso specificando una raccolta del tipo.
Java
autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));
Kotlin
autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))
L'esempio di codice riportato di seguito mostra come chiamare setTypesFilter() su un
IntentBuilder per impostare un filtro che restituisca solo i risultati con un indirizzo preciso,
specificando una raccolta del tipo.
Java
Intent intent = new Autocomplete.IntentBuilder(
AutocompleteActivityMode.FULLSCREEN, fields)
.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
.build(this);
Kotlin
val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
.setTypesFilter(listOf(PlaceTypes.ADDRESS))
.build(this)
Filtra i risultati per paese
Per filtrare i risultati del completamento automatico fino a un massimo di cinque paesi, chiama
setCountries()
per impostare il codice paese.
Passa il filtro a un frammento o a un intent. I paesi devono essere trasmessi come codice paese compatibile con lo standard ISO 3166-1 Alpha-2.
L'esempio di codice riportato di seguito mostra la chiamata a setCountries() su
AutocompleteSupportFragment, per impostare un filtro che restituisca solo i risultati
nei paesi specificati.
Java
autocompleteFragment.setCountries("AU", "NZ");
Kotlin
autocompleteFragment.setCountries("AU", "NZ")
Limiti di utilizzo
Il tuo utilizzo dell'API Places, incluso l'SDK Places per Android, non è più limitato a un numero massimo di richieste al giorno (QPD). Tuttavia, vengono ancora applicati i seguenti limiti di utilizzo:
- Il limite di frequenza è 100 richieste al secondo (QPS). Viene calcolato come la somma delle richieste lato client e lato server per tutte le applicazioni che utilizzano le credenziali dello stesso progetto.
Attribuzioni display nell'app
- Se la tua app utilizza il servizio di completamento automatico in modo programmatico, l'interfaccia utente deve mostrare un'attribuzione "Fornita da Google" oppure essere visualizzata in una mappa con brand Google.
- Se la tua app utilizza il widget di completamento automatico, non sono necessarie ulteriori azioni (l'attribuzione richiesta viene visualizzata per impostazione predefinita).
- Se recuperi e mostri informazioni aggiuntive sul luogo dopo aver ricevuto un luogo tramite ID, devi mostrare anche le attribuzioni di terze parti.
Per ulteriori dettagli, consulta la documentazione sulle attribuzione.
Effettua l'ottimizzazione del completamento automatico
Questa sezione descrive le best practice per aiutarti a ottenere il massimo dal servizio Place Autocomplete.
Di seguito sono riportate alcune linee guida generali:
- Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare il widget Autocomplete dell'API Maps JavaScript, il widget Autocomplete dell'SDK Places per Android o il controllo dell'interfaccia utente di completamento automatico dell'SDK Places per iOS
- Comprendi fin da subito i campi di dati di completamento automatico dei luoghi.
- I campi della geolocalizzazione e della limitazione della località sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
- Utilizza la gestione degli errori per assicurarti che la tua app presenti una riduzione controllata se l'API restituisce un errore.
- Assicurati che la tua app sia gestita quando non è presente alcuna selezione e offre agli utenti un modo per continuare.
Best practice per l'ottimizzazione dei costi
Ottimizzazione dei costi di base
Per ottimizzare i costi di utilizzo del servizio di completamento automatico dei luoghi, utilizza le maschere di campo nei widget Dettagli luogo e Inserisci completamento automatico per restituire solo i campi di dati dei luoghi necessari.
Ottimizzazione avanzata dei costi
Prendi in considerazione l'implementazione programmatica del completamento automatico di Place per accedere ai prezzi per richiesta e richiedere i risultati dell'API Geocoding anziché il luogo selezionato, anziché Dettagli luogo. I prezzi per richiesta abbinati all'API Geocoding sono più vantaggiosi dei prezzi per sessione (basati su sessione) se sono soddisfatte entrambe le seguenti condizioni:
- Se ti servono soltanto la latitudine/longitudine o l'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni per meno di una chiamata con Dettagli luogo.
- Se gli utenti selezionano una previsione di completamento automatico entro una media di massimo quattro richieste di previsioni di completamento automatico, il prezzo per richiesta potrebbe essere più conveniente di quello per sessione.
La tua applicazione richiede informazioni diverse dall'indirizzo e dalla latitudine/longitudine della previsione selezionata?
Sì, ho bisogno di ulteriori dettagli
Utilizza il completamento automatico dei luoghi basato sulla sessione con i dettagli del luogo.
Poiché la tua applicazione richiede dettagli relativi al luogo, come il nome del luogo, lo stato dell'attività o l'orario di apertura, l'implementazione del completamento automatico dei luoghi dovrebbe utilizzare un token di sessione (a livello programmatico o integrato nei widget JavaScript, Android o iOS) per un costo totale di 0,017 per sessione più gli SKU di dati dei luoghi applicabili, a seconda dei campi dei dati dei luoghi richiesti.6
Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Place Autocomplete che la richiesta Place Details nella previsione selezionata. Assicurati di specificare il parametro fields per assicurarti di richiedere solo i campi dei dati relativi ai luoghi di cui hai bisogno.
Implementazione della pubblicità programmatica
Utilizza un token di sessione con le richieste di completamento automatico dei luoghi. Quando richiedi i dettagli del luogo relativi alla previsione selezionata, includi i seguenti parametri:
- L'ID luogo dalla risposta di completamento automatico del luogo
- Il token di sessione utilizzato nella richiesta di completamento automatico dell'attività
- Il parametro
fieldsche specifica i campi di dati sul luogo necessari
No, necessita solo di indirizzo e posizione
L'API Geocoding potrebbe essere un'opzione più conveniente rispetto a Place Details per la tua applicazione, a seconda delle prestazioni dell'utilizzo di Place Autocomplete. L'efficienza del completamento automatico di ogni applicazione varia a seconda di cosa vi accedono gli utenti, dove viene utilizzato e se sono state implementate best practice per l'ottimizzazione delle prestazioni.
Per rispondere alla seguente domanda, analizza il numero di caratteri digitati da un utente in media prima di selezionare la previsione di completamento automatico dell'applicazione.
In media, gli utenti selezionano una previsione di completamento automatico del luogo in quattro richieste o meno?
Sì
Implementare Place Autocomplete in modo programmatico senza token di sessione e chiamare l'API Geocoding sulla previsione di luogo selezionata.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine a 0,005 $per richiesta. Il completamento di quattro richieste di tipo Compilazione automatica - Per richiesta costa 0,01132 $, quindi il costo totale di quattro richieste più una chiamata API Geocoding relativa alla previsione del luogo selezionato sarà di 0,01632 $, inferiore al prezzo di completamento automatico per sessione di 0,017 $per sessione.1
Valuta se utilizzare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano in un numero ancora inferiore di caratteri.
No
Utilizza il completamento automatico dei luoghi basato sulla sessione con i dettagli del luogo.
Poiché il numero medio di richieste che intendi effettuare prima che un utente selezioni una previsione di completamento automatico di un luogo supera il costo dei prezzi per sessione, l'implementazione del completamento automatico di questo luogo dovrebbe utilizzare un token di sessione sia per le richieste di completamento automatico del luogo che per la richiesta di dettagli del luogo associata per un costo totale di 0,017 $per sessione.1
Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Place Autocomplete che la richiesta Place Details nella previsione selezionata. Assicurati di specificare il parametro fields per assicurarti di richiedere solo i campi Dati di base.
Implementazione della pubblicità programmatica
Utilizza un token di sessione con le richieste di completamento automatico dei luoghi. Quando richiedi i dettagli del luogo relativi alla previsione selezionata, includi i seguenti parametri:
- L'ID luogo dalla risposta di completamento automatico del luogo
- Il token di sessione utilizzato nella richiesta di completamento automatico dell'attività
- Il parametro
fieldsche specifica i campi Dati di base, come indirizzo e geometria
Considera la possibilità di ritardare le richieste di completamento automatico dei luoghi
Puoi utilizzare strategie come ritardare una richiesta di completamento automatico dei luoghi fino a quando l'utente non ha digitato i primi tre o quattro caratteri, in modo che la tua applicazione faccia meno richieste. Ad esempio, effettuando richieste di completamento automatico del luogo per ogni carattere dopo che l'utente ha digitato il terzo carattere, se l'utente digita sette caratteri e poi seleziona una previsione per la quale si effettua una richiesta API Geocoding, il costo totale sarà di $0,01632 (4 * $0,00283 completamento automatico per richiesta + $0,005 Geocodifica).1
Se le richieste in ritardo possono ricevere una richiesta di pubblicità programmatica media inferiore a 4, puoi seguire le indicazioni per l'implementazione del completamento automatico dei luoghi con l'API Geocoding. Tieni presente che le richieste in ritardo possono essere percepite come latenza dall'utente, che potrebbe aspettarsi di vedere previsioni a ogni nuova sequenza di tasti.
Prova a utilizzare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano in meno caratteri.
-
I costi elencati qui sono in USD. Per informazioni complete sui prezzi, consulta la pagina Fatturazione di Google Maps Platform.
Best practice per il rendimento
Le seguenti linee guida descrivono i modi per ottimizzare le prestazioni di completamento automatico dei luoghi:
- Aggiungi limitazioni in base al paese, la previsione della località e (per le implementazioni programmatiche) la preferenza della lingua per l'implementazione del completamento automatico del luogo. La preferenza della lingua non è necessaria per i widget perché selezionano le preferenze relative alla lingua dal browser o dal dispositivo mobile dell'utente.
- Se il completamento automatico di un luogo è accompagnato da una mappa, puoi modificare la posizione in base alla visualizzazione della mappa.
- Nei casi in cui un utente non scelga una delle previsioni di completamento automatico, in genere perché nessuna di queste previsioni è l'indirizzo del risultato desiderato, puoi riutilizzare l'input originale dell'utente per tentare di ottenere risultati più pertinenti:
- Se prevedi che l'utente debba inserire solo le informazioni relative all'indirizzo, riutilizza l'input utente originale durante una chiamata all'API Geocoding.
- Se prevedi che l'utente inserirà query per un luogo specifico in base al nome o all'indirizzo, utilizza una richiesta Trova luogo. Se i risultati sono previsti solo in una regione specifica, utilizza la previsione della località.
- Gli utenti che inseriscono indirizzi di premessa nei paesi in cui il supporto della funzionalità di completamento automatico degli indirizzi di pre-ordine sono incompleti, ad esempio Cechia, Estonia e Lituania. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha" genera una previsione parziale nel Place Autocomplete.
- Gli utenti che inseriscono indirizzi con prefissi del segmento di strada come "23-30 29th St, Queens" a New York City o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai alle Hawaii.
Risoluzione dei problemi
Anche se può verificarsi un'ampia varietà di errori, è probabile che la maggior parte degli errori riscontrati dall'app sia dovuta a errori di configurazione (ad esempio, è stata usata la chiave API errata o la chiave API è stata configurata in modo errato) o errori di quota (l'app ha superato la quota). Per ulteriori informazioni sulle quote, consulta la pagina Limiti di utilizzo.
Gli errori che si verificano durante l'uso dei controlli di completamento automatico vengono restituiti nel callback onActivityResult(). Chiama Autocomplete.getStatus() per ricevere il messaggio di
stato relativo al risultato.