Configurare Navigation Connect

Sviluppatori dello Spazio economico europeo (SEE)

Questo documento descrive i passaggi necessari per iniziare a utilizzare Navigation Connect.

Prerequisiti

Questa guida mostra come configurare il tuo account Google Cloud e il tuo progetto cloud con la fatturazione abilitata. Inoltre, devi conoscere i costi associati all'utilizzo dell'API Navigation Connect.

  1. Esamina la fatturazione e i costi di utilizzo in Navigation Connect Usage and Billing.
  2. Verifica di avere un account Google Cloud.

    Accedi alla console Google Cloud
  3. Verifica di avere un progetto Google Cloud con la fatturazione abilitata.

    Vai alla pagina Fatturazione
    1. Seleziona il tuo progetto per aprire la pagina Fatturazione.
    2. Nella pagina Fatturazione:

      • Se la fatturazione è già abilitata per il progetto selezionato e hai un solo account di fatturazione, si apre la pagina Fatturazione.
      • Se hai più account di fatturazione, seleziona Vai all'account di fatturazione collegato per visualizzare i dettagli dell'account di fatturazione associato al progetto.
      • Se esiste un account di fatturazione, ma non è associato al progetto, ti verrà chiesto di collegare un account di fatturazione al progetto.
      • Se non esiste un account di fatturazione o se vuoi crearne uno nuovo, seleziona Gestisci account di fatturazione per creare un nuovo account di fatturazione. Per saperne di più, consulta Crea un nuovo account di fatturazione Cloud self-service.

Abilita l'API e verifica l'app

Questa guida descrive la procedura per attivare l'API Navigation Connect e verificare la tua app nella console Google Cloud, in modo che possa interfacciarsi in modo sicuro con Google Maps e Waze. Devi completare questa procedura per utilizzare l'API Navigation Connect.

1. Attiva l'API Navigation Connect

Utilizza la console Google Cloud o il comando gcloud per abilitare l'API Navigation Connect nel tuo progetto Google Cloud.

Per abilitare l'API, segui questi passaggi:

Console

  1. Apri la pagina di prodotto nella console Google Cloud:

    Abilita l'API Navigation Connect
  2. Fai clic sul pulsante Abilita.

gcloud

gcloud services enable \
    --project "PROJECT" \
    "navigationconnect.googleapis.com"

Scopri di più su Google Cloud SDK, sull'installazione di Cloud SDK e sui seguenti comandi:

2. Avvia la procedura di verifica dell'app

Dopo aver abilitato l'API, devi verificare la tua app per attivare l'API Navigation Connect. L'abilitazione dell'API da sola non concede l'accesso. Prima di poter utilizzare l'API Navigation Connect, devi fornire i dettagli dell'attività e dell'app per la revisione.

Per avviare la procedura di verifica, utilizza uno dei seguenti metodi:

  • API Marketplace:
    1. Nel Marketplace delle API, trova la scheda API Navigation Connect.
    2. Fai clic sull'icona blu Verifica richiesta per avviare la procedura di verifica.
  • Chiavi e credenziali nella console Google Cloud:
    1. Nella console Google Cloud, vai alla pagina Chiavi e credenziali.
    2. Fai clic su Chiavi e credenziali di Navigation Connect.
    3. Nel banner, fai clic su Avvia la verifica.

3. Fornisci i dettagli relativi all'app, alla raccolta dei dati e alla privacy

La tabella seguente descrive i dettagli che devi fornire per la verifica dell'app:

Campo Descrizione
Dettagli sull'app

Fornisci i seguenti dettagli per assicurarti che la tua app venga visualizzata correttamente in Google Maps e Waze.

Nome dell'attività o dell'app Inserisci il nome da mostrare agli utenti in Google Maps e Waze.
Identificatore dell'applicazione Fornisci il nome del pacchetto Android o l'ID pacchetto iOS.
Link universale per iOS Fornisci il link universale per iOS che consente agli utenti di tornare alla tua app (disponibile solo su Waze).
Logo dell'app (solo Waze) (Facoltativo) Carica un logo PNG o JPG (da 32 x 32 a 128 x 128 pixel) per visualizzare il logo della tua app in Waze durante una sessione di navigazione.
Dettagli sulla raccolta dei dati e sulla privacy

Inserisci i seguenti dettagli per garantire trasparenza, fiducia dei conducenti e sicurezza dei dati.

Link alle norme sulla privacy Fornisci l'URL delle norme sulla privacy della tua app. Questo link viene visualizzato nella schermata per il consenso.
Titolari del trattamento dei dati aggiuntivi (facoltativo) Fornisci il nome commerciale e il link alle norme sulla privacy di eventuali gestori dei dati di terze parti, ad esempio ISV. Questi dettagli vengono visualizzati nella schermata per il consenso.
Conformità dei dati Se la tua app opera negli Stati Uniti, seleziona la casella di controllo Questa app verrà utilizzata per i viaggi negli Stati Uniti per garantire la conformità alle normative locali.

4. Rivedi e invia

Rivedi il riepilogo delle informazioni fornite prima di inviare l'app per la verifica.

  1. Esamina attentamente il nome, la piattaforma, gli ID e i link dell'app.

  2. Seleziona la casella di controllo Tutte le informazioni sono corrette.
  3. Fai clic su Invia.

Dopo aver inviato l'app per la verifica, inizia la fase di revisione.

  • Tempistiche: la verifica richiede in genere 1-3 giorni lavorativi.
  • Notifica: ricevi un'email quando lo stato della verifica cambia. Riceverai anche un'email con la richiesta del tuo ID profilo pagamenti o del tuo ID sviluppatore Android. Se hai bisogno di un ID sviluppatore Android, consulta Creazione di un account sviluppatore.
  • Monitoraggio dello stato: monitora i tuoi progressi nella pagina Chiavi e credenziali della console Google Cloud.
  • Assistenza: per aggiornare la configurazione dopo l'approvazione senza influire sulla produzione, crea un ticket di assistenza.

Una volta verificata, la tua app è autorizzata a utilizzare l'API Navigation Connect per generare token di percorso che autorizzano l'accesso a una sessione di navigazione e ti consentono di ricevere i dettagli del percorso da Google Maps e Waze.

I prodotti Google Maps Platform richiedono che le chiamate API includano un token OAuth per impedire l'utilizzo non autorizzato.

Crea un token OAuth

Navigation Connect supporta OAuth 2.0 per l'autenticazione. Google supporta scenari OAuth 2.0 comuni, ad esempio per un server web.

Questo documento descrive come passare un token OAuth a una chiamata di Navigation Connect nel tuo ambiente di sviluppo. Per saperne di più sull'utilizzo di OAuth in un ambiente di produzione, consulta Metodi di autenticazione di Google.

Puoi chiamare le API di Google Maps direttamente inviando richieste API al server oppure puoi utilizzare le librerie client per semplificare il codice. Google Maps fornisce librerie client per Go, Java, Node.js e Python. Per saperne di più, consulta Librerie client di Navigation Connect.

Panoramica di OAuth

Puoi creare e gestire i token di accesso con OAuth in diversi modi, a seconda dell'ambiente di deployment.

Puoi utilizzare OAuth 2.0 per le interazioni server-to-server tra la tua applicazione e un servizio Google. Per questo scenario, utilizzi un service account associato alla tua applicazione anziché a un singolo utente. Puoi effettuare richieste API utilizzando il service account senza coinvolgere direttamente gli utenti. Per saperne di più sui metodi di autenticazione, consulta Metodi di autenticazione di Google.

In alternativa, puoi integrare Navigation Connect in un'app mobile Android o iOS. Per ulteriori informazioni sull'utilizzo di OAuth e sulla gestione dei token di accesso per diversi ambienti di deployment, consulta Utilizzo di OAuth 2.0 per accedere alle API di Google.

Ambiti OAuth

Per utilizzare OAuth con Navigation Connect, devi assegnare al token OAuth il seguente ambito:

https://www.googleapis.com/auth/cloud-platform

Esempio: prova le chiamate API REST nel tuo ambiente di sviluppo locale

Se non hai un ambiente che genera token e vuoi provare Navigation Connect con un token OAuth, utilizza la procedura descritta in questa sezione.

Questo esempio descrive come utilizzare il token OAuth fornito dalle Credenziali predefinite dell'applicazione (ADC) per effettuare la chiamata. Per saperne di più sull'utilizzo di ADC per chiamare le API di Google con le librerie client, consulta Autenticati utilizzando le librerie client.

Utilizza la seguente procedura REST solo per lo sviluppo o i test, non per la produzione.

Prerequisiti

Prima di effettuare una richiesta REST utilizzando ADC, utilizza l'interfaccia a riga di comando gcloud per fornire le credenziali ad ADC:

  1. Installa e inizializza l'interfaccia a riga di comando gcloud. Per saperne di più, consulta Installa gcloud CLI.

  2. Esegui l'autenticazione con l'interfaccia a riga di comando gcloud:

    gcloud auth application-default login
  3. Completa la procedura di accesso per salvare le tue credenziali nel file delle credenziali locali utilizzato da ADC.

Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale.

Effettua una richiesta REST

In questo esempio, passi due intestazioni della richiesta:

  • Passa il token OAuth nell'intestazione Authorization utilizzando il seguente comando per generare il token:

    gcloud auth application-default print-access-token

    Il token restituito ha un ambito di https://www.googleapis.com/auth/cloud-platform.

  • Passa l'ID o il nome del tuo progetto cloud Google Cloud con la fatturazione abilitata nell'intestazione X-Goog-User-Project.

Per chiamare Navigation Connect utilizzando un token OAuth, completa i seguenti passaggi:

  1. Nel seguente esempio di codice, sostituisci i segnaposto con i tuoi valori:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud
    • ANDROID_APP_ID: il nome del pacchetto Android della tua app, se applicabile
    • IOS_APP_ID: l'ID pacchetto iOS della tua app, se applicabile
    #!/bin/bash
    trip_id="$(uuidgen)"
    access_token="$(gcloud auth application-default print-access-token)"
    curl -X POST "https://navigationconnect.googleapis.com/v1/projects/PROJECT_ID/trips?tripId=${trip_id}" \
    -H "Authorization: Bearer ${access_token}" \
    -H "Content-Type: application/json" \
    -d '{
    "androidAppId": "ANDROID_APP_ID",
    "iosAppId": "IOS_APP_ID",
    }'
  2. Per copiare il comando curl, fai clic su Copia nell'esempio di codice.

  3. Incolla il comando in una finestra del terminale, quindi eseguilo.

La risposta è un oggetto JSON:

{
  "name": "projects/PROJECT_NUMBER/trips/TRIP_ID",
  "authToken": {
    "token": "BASE64_ENCODED_TRIP_TOKEN",
    "expireTime": "2026-03-06T11:09:47.476942Z"
  },
  "state": "NEW",
  "execution": {
    "traveledDistanceMeters": 0,
    "stopAddedInRoute": false
  },
  "createTime": "2026-03-05T23:09:50.768959Z",
  "updateTime": "2026-03-05T23:09:50.768959Z",
}

Questa risposta include i seguenti valori:

  • PROJECT_NUMBER: l'identificatore univoco di tipo intero lungo del progetto
  • TRIP_ID: l'ID percorso UUIDv4 generato dal tuo backend
  • BASE64_ENCODED_TRIP_TOKEN: il token autenticato restituito dal metodo createTrip per avviare la navigazione passo passo monitorata in Google Maps o Waze

Risoluzione dei problemi

Se la richiesta restituisce un messaggio di errore che indica che questa API non supporta le credenziali dell'utente finale, consulta Risolvi i problemi di configurazione di ADC.

Passaggi successivi

Successivamente, configura i service account per l'API Navigation Connect in modo da supportare la comunicazione server-server sicura tra la tua infrastruttura di backend, Google Maps e Waze.

Configura il service account