Scegli la versione dell'SDK

L'SDK Places SDK for Android versione 3.4.0 supporta due versioni di SDK: L'SDK Places per Android è l'SDK esistente e l'SDK Places per Android (nuovo) è la versione di nuova generazione dell'SDK.

Nota: tutte le nuove funzionalità incluse in questa release fanno parte dell'SDK Places per Android (nuovo) e non sono disponibili nell'SDK Places per Android.

Con il rilascio dell'SDK Places per Android versione 3.4.0, la tua prima attività è decidere quale SDK utilizzare. Questo vale se sei un nuovo cliente o un cliente esistente che utilizza già l'SDK. Utilizza questa guida per comprendere le principali differenze tra i due SDK.

Come selezionare la versione dell'SDK

Nel backend, Places SDK for Android si basa sul servizio API Places, API Places (nuova) o API Places. Prima di poter utilizzare Places SDK for Android, devi abilitare il servizio API Places nel tuo progetto Google Cloud.

Per Android, ci sono due azioni che devi intraprendere per stabilire quali API puoi utilizzare nella tua app:

1. Nel tuo progetto, devi abilitare l'API Places (nuova), l'API Places o entrambe nella chiave API, a seconda di quale vuoi utilizzare nella tua app.

2. Inizializza l'app chiamando il metodo Places.initializeWithNewPlacesApiEnabled() o Places.initialize().

Seleziona il tuo SDK

La versione del servizio API Places che attivi controlla la versione dell'SDK utilizzata dalla tua app:

• Entrambi: attiva tutte le funzionalità sia per l'SDK Places per Android che per l'SDK Places per Android (nuovo). Usa i metodi Places.initializeWithNewPlacesApiEnabled() e Places.initialize() per controllare le funzionalità disponibili.

• API Places: abilita l'SDK Places per Android esistente. Non hai accesso alle nuove funzionalità aggiunte in Places SDK for Android versione 3.4.0.

• API Places (nuova): abilita l'SDK Places per Android (nuovo) e tutte le nuove funzionalità descritte in Funzionalità principali aggiunte all'SDK Places per Android (novità), ma non attiva funzionalità esistenti come Luogo attuale e completamento automatico di Place.

Per ulteriori informazioni sulla selezione del servizio API Places, vedi Configurare il progetto Google Cloud.

Inizializza la tua app

Quando inizializza l'app, devi chiamare il metodo Places.initializeWithNewPlacesApiEnabled() o Places.initialize().

La tabella seguente mostra gli effetti dell'abilitazione di ogni SDK e della chiamata di ciascun metodo di inizializzazione. Ad esempio, se abiliti l'SDK Places (Nuovo) e chiami Places.initializeWithNewPlacesApiEnabled(), puoi utilizzare tutte le nuove API e tutte le API esistenti.

Se attivi l'SDK Places (nuovo) e chiami Places.initialize(), non puoi utilizzare le nuove funzionalità di Place Details e Place Photo, ma puoi chiamare la nuova ricerca testuale. Se non abiliti l'API Places, non puoi accedere alla versione precedente di Place Details, ma puoi comunque chiamare la nuova ricerca testuale.

Versione	API	SDK abilitato nella chiave API		Metodo di inizializzazione
		API Places	API Places (novità)	initialize()	initializeWithNewPlacesApiEnabled()
v3.3.0	Places Details
	Dettagli luogo (novità)
	Metadati delle foto (novità)
	Ricerca testuale (novità)			Entrambi i metodi
v3.4.0	URI fotografico (nuovo)
	Bitmap foto			Entrambi i metodi
	CurrentPlace			Entrambi i metodi
	Completamento automatico			Entrambi i metodi

Quale SDK scegli?

Per decidere quale versione scegliere:

1. Se sei un nuovo cliente che ha appena iniziato a utilizzare l'SDK Places per Android, inizia con l'API Places (nuova) e il nuovo SDK.

2. Se sei uno sviluppatore Kotlin, puoi utilizzare entrambi gli SDK, ma le nuove funzionalità dell'SDK Places per Android (nuovo) sono disponibili solo in Java nella versione 3.4.0.

3. Se sei un cliente esistente e utilizzi i token di sessione, continua a usare l'SDK esistente. L'SDK Places per Android (nuova) al momento non supporta i token di sessione.

4. Se sei un cliente esistente, puoi continuare a utilizzare l'SDK esistente. Tuttavia, per sfruttare i miglioramenti delle prestazioni e i miglioramenti delle funzionalità dell'SDK Places per Android (novità), puoi utilizzare il nuovo SDK.

   Non è necessaria alcuna migrazione quando si passa al nuovo SDK. Devi solo:

   1. Attiva l'API Places (nuova) sulla chiave API utilizzata nella tua app. Per ulteriori informazioni, consulta la pagina relativa all'utilizzo delle chiavi API.

   2. Nella sezione dependencies del file build.gradle a livello di modulo, aggiorna la dipendenza places e aggiungi la dipendenza kotlin-bom:

        dependencies {
            implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
            implementation 'com.google.android.libraries.places:places:3.3.0'
        }

      Per maggiori informazioni sulla dipendenza kotlin-bom, consulta Utilizzo della versione di kotlin-stdlib più recente nelle dipendenze transitive.

   3. Aggiorna l'app esistente per chiamare il nuovo metodo Places.initializeWithNewPlacesApiEnabled() per inizializzare l'app. Per saperne di più, consulta Inizializzare il client API Places.

   Le app esistenti continuano a funzionare senza modifiche, ma ora puoi usufruire di tutte le nuove funzionalità dell'SDK.

Funzionalità principali aggiunte a Places SDK for Android (novità)

Questa sezione illustra le funzionalità principali aggiunte all'SDK Places per Android (novità).

Implementata sulla piattaforma Google Cloud standard

L'SDK Places for Android (New) è implementato nell'infrastruttura dei servizi su Google Cloud. Questa implementazione offre una piattaforma più sicura e affidabile. Questo design standard offre un livello di coerenza tra gli SDK che migliorano l'efficienza dello sviluppo con Places SDK for Android (Novità).

Prestazioni migliorate

L'SDK Places for Android (New) offre prestazioni migliori, pertanto vale la pena sostituire le app che utilizzano l'SDK esistente.

Nuovo servizio di ricerca testuale

La ricerca testuale restituisce informazioni su un insieme di luoghi in base a una stringa, ad esempio "pizza a New York" o "negozi di scarpe vicino a Ottawa" o "123 Main Street". Il servizio risponde con un elenco di luoghi corrispondenti alla stringa di testo e con eventuali bias di località impostati.

Nuovi dati di risposta aggiunti a Dettagli sul luogo e Foto del luogo

• Place Details ora include la nuova classe Review nell'oggetto Place risposta. La classe Place contiene il nuovo metodo getReviews() per supportare questo campo. Chiama il numero getReviews() per visualizzare fino a cinque recensioni per un luogo.

• Foto del luogo aggiunge AuthorAttributions al corso PhotoMetadata. AuthorAttributions contiene List di oggetti AuthorAttribution.

Nuova risposta URI aggiunta a Place Photo

Ora puoi utilizzare Place Photo per restituire un URI a una bitmap di immagine. In precedenza, potevi solo restituire la bitmap dell'immagine stessa.

Prezzi semplificati

I prezzi sono semplificati con l'SDK Places for Android (Nuovo) in modo che tu paghi solo per i dati che utilizzi. I prezzi semplificati vengono implementati utilizzando elenchi di campi, chiamati anche mascherine di campo.

Con Place Details e la ricerca di testo puoi utilizzare gli elenchi di campi per controllare l'elenco di campi da restituire nella risposta. Ti vengono quindi addebitati solo i dati richiesti. L'utilizzo di un elenco di campi è una buona pratica di progettazione per garantire di non richiedere dati superflui, il che contribuisce a evitare tempi di elaborazione e addebiti di fatturazione superflui.

Per informazioni dettagliate sui prezzi di entrambi gli SDK, consulta la pagina Utilizzo e fatturazione.

Nota: il nuovo modello di determinazione del prezzo si applica solo a Dettagli del luogo, Ricerca testuale e Foto del luogo. I prezzi di Place Autocomplete e Current Place sono gli stessi per entrambi gli SDK.

Tipi di luoghi espansi

Il nuovo SDK aggiunge i tipi di luogo mostrati nella seguente tabella. Questi tipi vengono restituiti come parte delle risposte di Place Details e Ricerca testuale. Puoi anche utilizzare questi nuovi tipi, e quelli esistenti, in una ricerca con Ricerca testuale. I nuovi tipi sono inclusi nella Tabella A.

Tipo
american_restaurant	discount_store	ice_cream_shop	sandwich_shop
amusement_center	dog_park	indian_restaurant	school_district
athletic_field	electric_vehicle_charging_station	indonesian_restaurant	seafood_restaurant
auto_parts_store	event_venue	italian_restaurant	ski_resort
banquet_hall	extended_stay_hotel	japanese_restaurant	spanish_restaurant
barbecue_restaurant	farm	korean_restaurant	sporting_goods_store
barber_shop	agriturismo	lebanese_restaurant	sports_club
bed_and_breakfast	fast_food_restaurant	Marina	sports_complex
brazilian_restaurant	ferry_terminal	mercato	steak_house
breakfast_restaurant	fitness_center	medical_lab	sushi_restaurant
brunch_restaurant	french_restaurant	mediterranean_restaurant	swimming_pool
bus_stop	gift_shop	mexican_restaurant	su misura
camping_cabin	golf_course	middle_eastern_restaurant	telecommunications_service_provider
cell_phone_store	greek_restaurant	motel	thai_restaurant
child_care_agency	grocery_store	national_park	transit_depot
chinese_restaurant	guest_house	park_and_ride	truck_stop
coffee_shop	hair_salon	performing_arts_theater	turkish_restaurant
community_center	hamburger_restaurant	pizza_restaurant	vegan_restaurant
consulente	eliporto	playground	vegetarian_restaurant
convention_center	hiking_area	scuola materna	vietnamese_restaurant
cottage	historical_landmark	private_guest_room	visitor_center
courier_service	home_improvement_store	ramen_restaurant	wedding_venue
cultural_center	ostello	resort_hotel	grossista
dental_clinic	hotel	rest_stop

Insieme a questi nuovi tipi, l'API Places (Nuova) ha spostato i seguenti tipi dalla Tabella B dalla Tabella A. Ciò significa che ora puoi utilizzare i seguenti tipi in una ricerca:

• country
• administrative_area_level_1
• administrative_area_level_2
• postal_code
• locality