Avviare Google Maps o Waze

Per avviare la sessione di navigazione, la tua app deve creare dinamicamente un URL di avvio per aprire Google Maps o Waze. Questa guida descrive come utilizzare il token di viaggio autenticato da Crea un viaggio per avviare Google Maps o Waze e configurare l'esperienza di ritorno alla tua app.

Come avviare Google Maps o Waze

Per avviare Google Maps o Waze, devi fornire un modo per consentire ai conducenti di avviare una sessione di navigazione dalla tua app, creare l'URL di avvio con i parametri richiesti e fornire l'ID applicazione per attribuire la sessione.

Consentire ai conducenti di avviare la navigazione dalla tua app

Devi fornire ai conducenti un modo per avviare la navigazione dalla tua app. Se consenti ai conducenti di avviare Google Maps o Waze utilizzando un pulsante, assicurati che l'attribuzione sia corretta ed evita confusione etichettandolo chiaramente. Ad esempio, inserisci il testo "Google Maps" o "Waze" sul pulsante o nelle sue vicinanze.

Creare l'URL di avvio

Per avviare una sessione di navigazione, crea un URL di avvio di Navigation Connect. Questo URL è una stringa contenente la destinazione, il token di viaggio e i parametri di navigazione richiesti. Funziona in modo simile a un URL di Google Maps standard o a un link diretto di Waze.

Per avviare Google Maps o Waze sul dispositivo del conducente, utilizza il meccanismo specifico della piattaforma:

• Android: passa la stringa dell'URL in un Intent.
• iOS: utilizza la stringa dell'URL come link universale (o link diretto).

Formattare la destinazione

Per assicurarti che Google Maps o Waze possano calcolare correttamente un percorso, rispetta le seguenti regole quando formatti la destinazione:

• Specifica esattamente una destinazione raggiungibile. Puoi passare la destinazione come stringa di indirizzo, coordinate di latitudine/longitudine o ID luogo.

• Non utilizzare più tappe. Se passi più tappe direttamente nell'URL, Google Maps o Waze visualizza un errore. Crea invece viaggi separati.

Nota: non passare un'origine di partenza personalizzata nell'URL di avvio. Google Maps o Waze utilizza automaticamente la posizione attuale del conducente all'avvio della sessione. Per evitare errori di tipo "Origine non trovata", richiedi ai conducenti di attivare il monitoraggio della posizione precisa.

Aggiungere il token di viaggio e i parametri di navigazione

Per completare l'URL di avvio, devi includere il token di viaggio autenticato che hai ricevuto dalla richiesta Crea un viaggio. Devi anche includere i parametri di navigazione che indicano a Google Maps o Waze di avviare la navigazione attiva.

Google Maps

Per Google Maps, includi i seguenti parametri nell'URL di avvio:

• dir_action=navigate: Questo parametro forza la navigazione attiva.
• action_token: questo parametro fornisce il token di viaggio autenticato.

I seguenti esempi mostrano come formattare l'URL di avvio per Google Maps utilizzando diversi formati di destinazione:

• Coordinate di latitudine/longitudine:

  https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN

• Stringa di indirizzo:

  https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN

• ID luogo:

  https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN

Waze

Per Waze, includi i seguenti parametri nell'URL di avvio:

• navigate=yes: questo parametro forza la navigazione attiva.
• external_trip_token: questo parametro fornisce il token di viaggio autenticato.

I seguenti esempi mostrano come formattare l'URL di avvio per Waze utilizzando diversi formati di destinazione:

• Coordinate di latitudine/longitudine:

  https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN

• Stringa di indirizzo:

  https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN

  Nota: Waze naviga verso il primo risultato di ricerca per le stringhe di indirizzo.
• ID luogo:

  https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN

Fornire l'ID applicazione (solo Android)

Per attribuire una sessione di navigazione alla tua app su Android, fornisci l'ID applicazione verificato. In questo modo, la tua app viene identificata come origine del viaggio, in modo che Google Maps o Waze possano ricollegare il viaggio attivo alla tua piattaforma.

Nota: per iOS, devi aver fornito l'ID applicazione nel messaggio CreateTripRequest. Per maggiori dettagli, vedi Creare un viaggio.

Se fornisci l'ID applicazione, puoi utilizzare le seguenti funzionalità:

• Autorizzare la condivisione dei dati: verifica che la tua app sia autorizzata a ricevere i dati sul percorso attivi.
• Attivare il consenso del conducente: compila la schermata di consenso con il nome della tua attività e le norme sulla privacy, assicurandoti che il conducente sappia chi riceve la sua posizione in tempo reale e l'ETA.
• Attivare il pulsante di ritorno: consente a Google Maps o Waze di creare un pulsante di ritorno con brand in modo che i conducenti possano tornare alla tua app.

Per passare l'ID applicazione a Google Maps o Waze su Android, aggiungi il nome del pacchetto all'intent di avvio (che contiene la stringa dell'URL di avvio) utilizzando Intent.EXTRA_REFERRER_NAME.

Il seguente esempio mostra come aggiungere il nome del pacchetto all'intent:

intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")

Come consentire ai conducenti di tornare alla tua app

Navigation Connect mostra una barra inferiore (Google Maps) o un pulsante Indietro con brand (Waze) in modo che il conducente possa tornare facilmente alla tua app in qualsiasi momento durante il viaggio o quando arriva a destinazione.

Android

Devi creare un PendingIntent che rimandi all' attività della tua app. Collega questo PendingIntent come extra all'intent di avvio utilizzando la chiave esatta "pendingIntent". Quando l'utente tocca il pulsante di ritorno, Google Maps o Waze esegue questo intent per portare la tua app in primo piano.

intent.putExtra("pendingIntent", getPendingIntent())

iOS (solo Waze)

Non devi aggiungere nulla all'URL di avvio per attivare il pulsante di ritorno. Waze utilizza automaticamente il link universale che hai registrato quando hai verificato la tua app.

Esempi di codice

I seguenti esempi di codice mostrano come avviare Google Maps o Waze dalla tua app utilizzando Navigation Connect e attivare il pulsante "Torna all'app".

Google Maps (Android)

Il seguente codice Kotlin mostra una funzione di esempio che avvia una sessione di Navigation Connect con i parametri richiesti.

private val destinationAddress = "1600 Amphitheatre Parkway, Mountain View, CA 94043"

        private fun launchNavConnect() {
           val jwtToken = "TRIP_TOKEN"

           try {
               // URL Encode the destination
               val encodedDestination = URLEncoder.encode(destinationAddress, "UTF-8")
               val navConnectUrl = "https://www.google.com/maps/dir/?api=1" +
                       "&destination=$encodedDestination" +
                       "&dir_action=navigate" +
                       "&action_token=$jwtToken"

               val intent = Intent(Intent.ACTION_VIEW, Uri.parse(navConnectUrl))
               // Explicitly set GMM package to ensure it opens in Google Maps
               intent.setPackage("com.google.android.apps.maps")
               // Add your application ID to the intent
               intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
               // set up the NavConnect back button
               intent.putExtra("pendingIntent", getPendingIntent())
               startActivity(intent)

           } catch (e: Exception) {
               // handle errors
           }
        }

        private fun getPendingIntent(): PendingIntent? {
          val returnIntent = Intent(application, MainActivity::class.java) // replace with your activity to launch
          returnIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP)
          val flags = PendingIntent.FLAG_IMMUTABLE
          if (Build.VERSION.SDK_INT < Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            return PendingIntent.getActivity(application, 0, returnIntent, flags)
          }

          val options =
            ActivityOptions.makeBasic()
              .setPendingIntentCreatorBackgroundActivityStartMode(
                ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED
              )

          return PendingIntent.getActivity(application, 0, returnIntent, flags, options.toBundle())
        }

Waze (Android)

Il seguente codice Kotlin mostra una funzione di esempio che avvia una sessione di Navigation Connect con i parametri richiesti.

private val destinationAddress = "1600 Amphitheatre Parkway, Mountain View, CA 94043"

         private fun launchNavConnect() {
            val tripToken = "TRIP_TOKEN"

            try {
                // URL Encode the destination
                val encodedDestination = URLEncoder.encode(destinationAddress, "UTF-8")
                val navConnectUrl = "https://waze.com/ul?" +
                        "&q=$encodedDestination" +
                        "&navigate=yes" +
                        "&external_trip_token=$tripToken"

                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(navConnectUrl))
                // Explicitly set package name to ensure it opens in Waze
                intent.setPackage("com.waze")
                // Add your application ID to the intent
                val referrerName = "android-app://${application.packageName}"
                intent.putExtra(Intent.EXTRA_REFERRER_NAME, referrerName)

                // set up the NavConnect back button
                intent.putExtra("pendingIntent", getPendingIntent())
                startActivity(intent)

            } catch (e: Exception) {
                // handle errors
            }
         }

         private fun getPendingIntent(): PendingIntent? {
           val returnIntent = Intent(application, MainActivity::class.java) // replace with your activity to launch
           returnIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP)
           val flags = PendingIntent.FLAG_IMMUTABLE
           if (Build.VERSION.SDK_INT < Build.VERSION_CODES.VANILLA_ICE_CREAM) {
             return PendingIntent.getActivity(application, 0, returnIntent, flags)
           }

           val options =
             ActivityOptions.makeBasic()
               .setPendingIntentCreatorBackgroundActivityStartMode(
                 ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED
               )

           return PendingIntent.getActivity(application, 0, returnIntent, flags, options.toBundle())
         }

Waze (iOS)

Il seguente codice Swift mostra una funzione di esempio che avvia una session e di Navigation Connect con i parametri richiesti.

openWazeUrl(queryItems: [URLQueryItem(name: "q", value: "1600 Amphitheatre Parkway")])

        private func openWazeUrl(queryItems: [URLQueryItem]) {
          var components = URLComponents()
          components.scheme = "https"
          components.host = "waze.com"
          components.path = "/ul"

          // Create a mutable copy of the queryItems.
          var mutableQueryItems = queryItems

          // Add Trip Token
          guard let tokenText = tokenField.text, !tokenText.isEmpty else {
            return
          }
          let token = URLQueryItem(name: "external_trip_token", value: tokenText)

          mutableQueryItems.append(token)

          // Add compulsory params
          mutableQueryItems.append(URLQueryItem(name: "navigate", value: "yes"))

          // Construct and Launch URL
          components.queryItems = mutableQueryItems

          guard let url = components.url else {
            return
          }

          UIApplication.shared.open(url, options: [:], completionHandler: nil)
        }
       }