Google Maps per Android Automotive Intent

Tramite gli intent di Android, puoi avviare la navigazione in Google Maps per Android Automotive.

Panoramica

Questa pagina descrive gli intent che puoi utilizzare con Google Maps per Android Automotive. Per la documentazione dettagliata per gli sviluppatori Android, consulta quanto segue:

• Intent e filtri per intent
• Intent comuni alla piattaforma Android

Richieste di intent

Per avviare Google Maps per Android Automotive con un intent, devi prima creare un oggetto Intent, specificandone l'azione, l'URI e il pacchetto.

• Azione. Tutti gli intent di Google Maps vengono chiamati come azione View, ACTION_VIEW.

• URI. Gli intent di Google Maps utilizzano stringhe codificate URI che specificano un'azione scelta, insieme ad alcuni dati con cui eseguire l'azione.

• Pacchetto. La chiamata a setPackage("com.google.android.apps.maps") garantisce che l'app Google Maps per Android gestisca l'intent. Se il pacchetto non è impostato, il sistema determina quali app possono gestire l'intent. Se sono disponibili più app, potrebbe esserti chiesto quale vuoi utilizzare.

Dopo aver creato l'intent, puoi richiedere al sistema di avviare l'app correlata in diversi modi. Un metodo comune consiste nel passare l'intent al metodo startActivity(). Il sistema avvierà l'app necessaria, in questo caso Google Maps, e avvierà l'Activity corrispondente.

// Create a Uri from an intent string. Use the result to create an Intent.
Uri mapIntentUri =
Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
// Create an Intent from mapIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

Se il sistema non riesce a identificare un'app in grado di rispondere all'intent, la tua app potrebbe arrestarsi in modo anomalo. Per questo motivo, verifica prima che sia installata un'applicazione di ricezione prima di presentare uno di questi intent a un utente.

Per verificare che un'app sia disponibile a ricevere l'intent, chiama resolveActivity() sull'oggetto Intent. Se il risultato è diverso da null, esiste almeno un'app in grado di gestire l'intent ed è sicuro chiamare startActivity(). Se il risultato è nullo, non devi utilizzare l'intent e, se possibile, disattiva la funzionalità che lo richiama.

if (mapIntent.resolveActivity(getPackageManager()) != null) {
...
}

Ad esempio, per avviare la navigazione passo passo verso lo zoo di Taronga a Sydney, puoi utilizzare il seguente codice:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
startActivity(mapIntent);
}

Stringhe di query con codifica URI

Tutte le stringhe trasmesse agli intent di Google Maps devono essere codificate come URI. Ad esempio, la stringa "1st & Pike, Seattle" deve diventare 1st%20%26%20Pike%2C%20Seattle. Gli spazi nella stringa possono essere codificati con %20 o sostituiti con il segno più (+).

Puoi utilizzare il metodo android.net.Uri encode() per codificare le stringhe. Per esempio:

Uri mapIntentUri = Uri.parse("google.navigation:q=" + Uri.encode("1st & Pike, Seattle"));

Visualizzare una mappa

Utilizza l'intent geo: per visualizzare una mappa in una posizione e a un livello di zoom specifici. Ad esempio:

geo:latitude,longitude?z=zoom

Parametri

• latitude e longitude impostano il punto centrale della mappa.

• z imposta facoltativamente il livello di zoom iniziale della mappa. I valori accettati vanno da 0 (tutto il mondo) a 21 (singoli edifici). Il limite superiore può variare a seconda dei dati della mappa disponibili nella località selezionata.

Esempio

// Creates an intent that will load a map of San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Cerca una località

Utilizza questo intent per visualizzare le query di ricerca all'interno di un viewport specificato:

geo:latitude,longitude?q=query
geo:0,0?q=my+street+address

Parametri

Oltre ai parametri utilizzati per visualizzare una mappa, la Ricerca supporta questo parametro:

• q definisce i luoghi da evidenziare sulla mappa. Il parametro q è obbligatorio per tutte le richieste di ricerca. Accetta una località come nome di un luogo o indirizzo. La stringa deve essere sottoposta all'escape dell'URL, quindi un indirizzo come "City Hall, New York, NY" deve essere convertito in City+Hall%2CNew+York%2CNY.

Modificare i risultati di ricerca con le coordinate

Quando cerchi una posizione molto specifica, la latitudine e la longitudine non sono strettamente necessarie se incluse nel parametro q. Tuttavia, se non conosci l'indirizzo esatto o la query è ambigua, puoi tentare di influenzare i risultati della ricerca specificando una coordinata. Ad esempio, l'esecuzione di una ricerca di indirizzi per "Via Roma" potrebbe restituire troppi risultati:

// Searching for "101 Main Street" with no lat/long might return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

L'aggiunta di una latitudine e una longitudine all'URI intent sposta i risultati verso un'area specifica:

// Searches for "101 Main Street" near San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Cerca lungo il percorso

Se viene inviato un intento di ricerca geo:latitude,longitude?q=query durante la navigazione, viene attivata una ricerca lungo il percorso e la latitudine e la longitudine vengono ignorate.

Cercare categorie predefinite

Per supportare l'integrazione con il veicolo, Google Maps nell'auto supporta un intent che mostra queste categorie predefinite:

L'intent della categoria è nel formato geo:lat,lng?c=category.

Utilizza c=<pre-defined category> indipendentemente dalle impostazioni delle impostazioni internazionali dell'utente. Google Maps mostra risultati pertinenti nel locale appropriato per questa categoria. Ad esempio:

// Search for gas stations nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?c=gas_station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Altre ricerche per categoria

Se trasmetti un termine di ricerca generico (ad esempio "ristoranti" o "bar") nelle impostazioni internazionali dell'utente, Google Maps per Android Automotive cerca schede di attività che corrispondono ai criteri. Se nell'intent geo: vengono fornite latitudine e longitudine specifiche, la ricerca è incentrata su quella posizione. Se non viene specificata alcuna località (ad es. geo:0,0), Google Maps tenta di trovare schede di attività nelle vicinanze. Ad esempio:

// Search for restaurants nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Puoi distorcere ulteriormente i risultati di ricerca specificando un parametro di zoom insieme alla stringa di query. Nell'esempio seguente, l'aggiunta di uno zoom di 10 tenta di trovare ristoranti a livello di città anziché nelle vicinanze:

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Avviare la navigazione passo passo

Per la documentazione sull'avvio della navigazione passo passo su altri dispositivi Android, consulta Avviare la navigazione passo passo negli intent di Google Maps per Android.

Utilizza questo intent per avviare la navigazione di Google Maps con indicazioni stradali passo passo per uno o più indirizzi o coordinate specificati. Le indicazioni vengono sempre fornite dalla posizione attuale dell'utente.

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude
google.navigation:place=placename

Parametri

Per avviare la navigazione, utilizza place o q con waypoints, che è facoltativo. Per contrassegnare facoltativamente un waypoint come stazione di ricarica, consulta Inviare un itinerario per veicoli elettrici a Google Maps.

• q imposta l'endpoint per le ricerche di navigazione. Può trattarsi di una latitudine e longitudine o di un indirizzo formattato per la query. Se si tratta di una stringa di query che restituisce più di un risultato, verrà selezionato il primo.

• place imposta la destinazione su casa o lavoro. Specifica casa per raggiungere la casa dell'utente e lavoro per raggiungere il posto di lavoro dell'utente.

• avoid imposta le funzionalità che il percorso deve cercare di evitare. avoid è facoltativo e può essere impostato su uno o più dei seguenti valori:

  • t per i pedaggi
  • h per le autostrade
  • f per i traghetti

• waypoints specifica uno o più luoghi intermedi per indirizzare le indicazioni stradali alla destinazione finale specificata da q. Puoi specificare più tappe utilizzando il carattere della barra verticale (|) per separare i luoghi, ad esempio Berlin,Germany|Paris,France. Puoi utilizzare tutti i waypoint necessari. I waypoint verranno aggiunti al percorso nello stesso ordine in cui sono elencati nell'URL. Ogni waypoint può essere un indirizzo o coordinate di latitudine e longitudine separate da virgole; inoltre, puoi avere indirizzi e coordinate di latitudine e longitudine nello stesso intent. Le stringhe devono essere codificate come URL, quindi i waypoint come "Berlin,Germany|Paris,France" devono essere convertiti in Berlin%2CGermany%7CParis%2CFrance.

Esempi

Questo intent richiederà la navigazione passo passo per raggiungere lo zoo Taronga, a Sydney, Australia:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Se preferisci non pagare pedaggi o prendere un traghetto, puoi richiedere un itinerario che tenti di evitare queste situazioni:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Se invece preferisci raggiungere casa, utilizza:

Uri mapIntentUri = Uri.parse("google.navigation:place=home");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Per avviare la navigazione passo passo verso i tre indirizzi seguenti in ordine, passa dallo zoo di Taronga come destinazione finale q e da Google Sydney e dalla Sydney Opera House come tappe intermedie:

1. Google Sydney

2. Teatro dell'opera di Sydney

3. Taronga Zoo, Sydney, Australia

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7CSydney+Opera+House");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Analogamente a q, puoi rappresentare uno qualsiasi dei waypoint con una latitudine e una longitudine separate da virgole anziché con un indirizzo. Ad esempio, per avviare la stessa navigazione passando la latitudine e la longitudine del Teatro dell'opera di Sydney anziché l'indirizzo:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7C-33.856159,151.215256");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Inviare un piano di viaggio per veicoli elettrici a Google Maps

Utilizza questo intent di navigazione multi-destinazione per specificare alcune destinazioni come fermate di ricarica per veicoli elettrici (EV). Questo intent, che estende l'intent multi-waypoint, aiuta i conducenti a mantenere una carica della batteria del veicolo elettrico sufficiente per raggiungere le loro destinazioni sincronizzando le informazioni sulle tappe di ricarica tra le app di pianificazione dei viaggi per veicoli elettrici e Google Maps.

Per le tappe per ricarica, gli intenti di viaggio:

• Deve contenere un nome e le coordinate di latitudine e longitudine
• Può contenere facoltativamente una potenza di uscita, da utilizzare per il calcolo del tempo di ricarica

Google utilizza il nome e la latitudine/longitudine della stazione di ricarica per trovare un luogo corrispondente da visualizzare dati avanzati come tipi di connettori, totali, velocità e disponibilità in tempo reale, metodi di pagamento supportati e punti di interesse (POI) dell'host. Ad esempio, indicazioni stradali all'interno di parcheggi all'aperto per l'ultima parte della navigazione, orari di apertura, valutazioni. Per assicurarti che le stazioni di ricarica corrispondano bene ai dati di Google, utilizza un <brand name> specifico, ad esempio ChargePoint.

Parametri

I seguenti parametri ti consentono di specificare i dettagli della destinazione finale e di eventuali waypoint, inclusi quelli designati come stazioni di ricarica per veicoli elettrici.

Destinazione finale

Per impostare una stazione di ricarica come destinazione finale, utilizza:

• q: deve contenere il valore di latitudine e longitudine della stazione di ricarica.
• q_type: 1 specifica che la destinazione finale è una stazione di ricarica.
• q_name: il nome della destinazione finale. Obbligatorio se q_type è 1.
• q_power_output_kw: Un numero double per la potenza di uscita della stazione di ricarica in kilowatt. Facoltativo.

Waypoints

Per i waypoint, tutti i parametri sono array paralleli separati da una barra verticale (|) di valori nello stesso ordine dei waypoint, esclusa la destinazione finale. Una mancata corrispondenza nel numero di elementi negli array paralleli viene trattata come intent malformato.

Per aggiungere uno o più waypoint di stazioni di ricarica, utilizza i seguenti parametri, tutti facoltativi. Se una delle destinazioni è contrassegnata come stazione di ricarica, il nome del waypoint diventa obbligatorio per quella destinazione.

• waypoints: Elenco dei waypoint come descritto nell'intent di navigazione passo passo. Deve essere un valore di latitudine e longitudine per i waypoint delle stazioni di ricarica.

• waypoint_types: Tipi per waypoint specificati come numero. 0 è una fermata qualsiasi (valore predefinito) e 1 è la stazione di ricarica.

• waypoint_names: Nomi dei waypoint. Questo campo è obbligatorio per le stazioni di ricarica.

• waypoint_power_outputs_kw: Numeri doppi per la potenza della stazione di ricarica in kilowatt. Per le stazioni di ricarica, puoi specificare facoltativamente un valore di potenza di uscita del waypoint, che viene utilizzato come fallback se non viene trovata la stazione corrispondente. Uno slot vuoto indica che non è stato fornito alcun valore.

Comportamento dell'esperienza utente (UX)

Per gli intent di viaggio con più destinazioni, viene visualizzata la schermata di riepilogo del percorso, ma la navigazione non si avvia automaticamente.

Per un intent formattato correttamente, Google Maps mostrerà una schermata di panoramica del percorso per il viaggio. La schermata di riepilogo del percorso mostrerà tutti i waypoint e la destinazione finale dall'intent, con consigli di ricarica ove applicabile.

Per qualsiasi waypoint o destinazione finale contrassegnato come stazione di ricarica, Google Maps cercherà un luogo corrispondente nel database di Google. Per garantire che vengano visualizzate le informazioni migliori possibili per le stazioni di ricarica:

• Se viene trovata una corrispondenza, Google Maps utilizza i dati di Google per visualizzare la stazione di ricarica nell'interfaccia utente e fornire un consiglio di ricarica per la stazione di ricarica.

• Se non viene trovata una corrispondenza, i dati forniti nell'intent per una stazione di ricarica (latitudine-longitudine, nome e potenza) vengono utilizzati per visualizzare questa stazione di ricarica nell'interfaccia utente e fornire un consiglio di ricarica presso questa stazione.

Esempi

I seguenti esempi illustrano come creare intent per vari scenari di pianificazione di viaggi in EV, tra cui la navigazione tramite più stazioni di ricarica e la gestione di potenze sconosciute.

Raggiungere una destinazione finale passando per più stazioni di ricarica

Il seguente intent porta alla destinazione finale, Port Macquarie NSW, passando per due stazioni di ricarica, ChargePoint ed Evie.

Destinazioni in ordine:

1. Stazione di ricarica ChargePoint (posizione: -32.9599188,151.6240806, potenza erogata: 6,6 kW)

2. Stazione di ricarica Evie (posizione: -31.9432539,152.4699808, potenza erogata: 350 kW)

3. Port Macquarie NSW

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806%7C-31.9432539%2C152.4699808"
            + "&waypoint_types=1%7C1"
            + "&waypoint_names=ChargePoint+Charging+Station%7CEvie+Charging+Station"
            + "&waypoint_power_outputs_kw=6.6%7C350");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Potenza sconosciuta

Se il valore di potenza in uscita è sconosciuto, lascia vuoto lo spazio pertinente di waypoint_power_outputs_kw. Se tutti gli slot sono vuoti, non è necessario specificare il parametro waypoint_power_outputs_kw.

Destinazioni in ordine:

1. Stazione di ricarica ChargePoint (posizione: -32.9599188,151.6240806, potenza di uscita: sconosciuta)

2. Port Macquarie NSW

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806"
            + "&waypoint_types=1"
            + "&waypoint_names=ChargePoint+Charging+Station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Contrassegnare la destinazione finale come stazione di ricarica

Per contrassegnare la destinazione finale come stazione di ricarica, specifica i parametri q_type, q_name e q_power_output_kw.

Destinazioni in ordine:

1. Taronga Zoo, Sydney, Australia

2. Stazione di ricarica ChargePoint (posizione: -32.9599188,151.6240806, potenza in uscita: sconosciuta)

3. Stazione di ricarica Evie (posizione: -31.9432539,152.4699808, potenza in uscita: 350 kW)

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=-31.9432539,152.4699808&q_type=1&q_name=Evie+Charging+Station&q_power_output_kw=350"
            + "&waypoints=Taronga+Zoo%2C+Sydney+Australia%7C-32.9599188%2C151.6240806"
            + "&waypoint_types=0%7C1"
            + "&waypoint_names=%7CChargePoint+Charging+Station"
            + "&waypoint_power_outputs_kw=%7C");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Intent di azione

Sono disponibili i seguenti intent di azione con interfacce: