Google Haritalar veya Waze'i başlatma

Navigasyon oturumunu başlatmak için uygulamanızın, Google Haritalar'ı veya Waze'i açmak için dinamik olarak bir başlatma URL'si oluşturması gerekir. Bu kılavuzda, Google Haritalar veya Waze'i başlatmak ve uygulamanıza geri dönüş deneyimini yapılandırmak için Gezi oluşturma bölümündeki kimliği doğrulanmış gezi jetonunun nasıl kullanılacağı açıklanmaktadır.

Google Haritalar veya Waze'i başlatma

Google Haritalar veya Waze'i başlatmak için sürücülerin uygulamanızdan navigasyon oturumu başlatmasına olanak tanıyan bir yöntem sunmanız, gerekli parametrelerle başlatma URL'sini oluşturmanız ve oturumu ilişkilendirmek için uygulama kimliğinizi sağlamanız gerekir.

Sürücülerin uygulamanızdan navigasyonu başlatmasına izin verme

Sürücülerin uygulamanızdan navigasyonu başlatabilmesi için bir yöntem sunmanız gerekir. Sürücülerin bir düğme kullanarak Google Haritalar'ı veya Waze'i başlatmasına izin veriyorsanız uygun ilişkilendirmeyi sağlayın ve düğmeyi net bir şekilde etiketleyerek kafa karışıklığını önleyin. Örneğin, düğmenin üzerine veya yakınına "Google Haritalar" ya da "Waze" metnini yerleştirin.

Başlatma URL'sini oluşturma

Navigasyon oturumu başlatmak için bir Navigation Connect başlatma URL'si oluşturun. Bu URL; varış noktasını, gezi jetonunu ve gerekli navigasyon parametrelerini içeren bir dizedir. Standart bir Google Haritalar URL'si veya Waze derin bağlantısına benzer şekilde çalışır.

Sürücünün cihazında Google Haritalar'ı veya Waze'i başlatmak için platforma özel mekanizmayı kullanın:

  • Android: URL dizesini bir Intent içinde iletin.
  • iOS: URL dizesini Geçiş Bağlantısı (veya derin bağlantı) olarak kullanın.

Hedefi biçimlendirme

Google Haritalar veya Waze'in bir rotayı başarıyla hesaplayabilmesi için varış noktanızı biçimlendirirken aşağıdaki kurallara uyun:

  • Tam olarak bir tane erişilebilir hedef belirtin. Hedefi adres dizesi, enlem/boylam koordinatları veya yer kimliği olarak iletebilirsiniz.

  • Birden fazla yol noktası kullanmayın. Doğrudan URL'de birden fazla yol noktası iletirseniz Google Haritalar veya Waze hata gösterir. Bunun yerine ayrı geziler oluşturun.

Gezi jetonu ve navigasyon parametreleri ekleme

Başlatma URL'sini tamamlamak için Gezi oluşturma isteğinden aldığınız kimliği doğrulanmış gezi jetonunu eklemeniz gerekir. Ayrıca Google Haritalar veya Waze'e etkin navigasyonu başlatmasını söyleyen navigasyon parametrelerini de eklemeniz gerekir.

Google Haritalar

Google Haritalar için başlatma URL'nize aşağıdaki parametreleri ekleyin:

  • dir_action=navigate: Bu parametre, etkin navigasyonu zorunlu kılar.
  • action_token: Bu parametre, kimliği doğrulanmış gezi jetonunuzu sağlar.

Aşağıdaki örneklerde, farklı hedef biçimleri kullanarak Google Haritalar için başlatma URL'sinin nasıl biçimlendirileceği gösterilmektedir:

  • Enlem/boylam koordinatları:
    https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN
  • Adres dizesi:
    https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN
  • Yer kimliği:
    https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN

Waze

Waze için başlatma URL'nize aşağıdaki parametreleri ekleyin:

  • navigate=yes: Bu parametre, etkin navigasyonu zorunlu kılar.
  • external_trip_token: Bu parametre, kimliği doğrulanmış gezi jetonunuzu sağlar.

Aşağıdaki örneklerde, farklı hedef biçimleri kullanarak Waze için başlatma URL'sinin nasıl biçimlendirileceği gösterilmektedir:

  • Enlem/boylam koordinatları:
    https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN
  • Adres dizesi:
    https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN
  • Yer kimliği:
    https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN

Uygulama kimliğinizi girme (yalnızca Android)

Navigation Connect ile bir gezi başlatmak için Android'de uygulamanızla bir navigasyon oturumu ilişkilendirmeniz gerekir. Bunun için doğrulanmış uygulama kimliğinizi girin. Bu, uygulamanızı gezinin kaynağı olarak tanımlar. Böylece Google Haritalar veya Waze, etkin yolculuğu platformunuza geri bağlayabilir. Uygulama kimliğinin eksik veya geçersiz olması, gezi jetonu kimlik doğrulamasının başarısız olmasına neden olur.

Uygulama kimliğinizi sağladığınızda aşağıdaki özellikler etkinleştirilir:

  • Veri paylaşımını yetkilendirme: Uygulamanızın etkin gezi verilerini alma yetkisi olduğunu doğrular.
  • Sürücü iznini etkinleştirme: Kullanıcı rızası ekranını işletmenizin adı ve gizlilik politikasıyla doldurarak sürücünün, gerçek zamanlı konumunu ve TVS'sini kimin aldığını bilmesini sağlar.
  • Geri düğmesini etkinleştirme: Google Haritalar veya Waze'in, sürücülerin uygulamanıza geri dönebilmesi için markalı bir geri düğmesi oluşturmasını sağlar.

Uygulama kimliğini Android'de Google Haritalar veya Waze'e iletmek için Intent.EXTRA_REFERRER_NAME kullanarak paket adınızı başlatma intent'ine (başlatma URL dizesini taşır) ekleyin.

Aşağıdaki örnekte, paket adının intent'e nasıl ekleneceği gösterilmektedir:

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

Sürücülerin uygulamanıza dönmesine izin verme

Sol tarafta geri düğmesi, uygulama adı ve veri paylaşımı simgesinin bulunduğu alt çubuğun yer aldığı Google Haritalar uygulaması. Sağda, markalı geri düğmesi bulunan Waze uygulaması.

Navigation Connect, sürücünün yolculuk sırasında herhangi bir noktada veya varış noktasına ulaştığında uygulamanıza otomatik geçiş yapabilmesi için bir alt çubuk (Google Haritalar) veya markalı bir geri düğmesi (Waze) gösterir.

Android

Uygulamanızın etkinliğine yönlendiren bir PendingIntent oluşturmanız gerekir. Bu PendingIntent değerini, tam anahtar "pendingIntent" kullanarak başlatma intent'ine ek olarak ekleyin. Kullanıcı geri dön düğmesine dokunduğunda Google Haritalar veya Waze, uygulamanızı ön plana getirmek için bu intent'i yürütür.

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

iOS (yalnızca Waze)

Geri düğmesini etkinleştirmek için başlatma URL'sine herhangi bir şey eklemeniz gerekmez. Waze, uygulamanızı doğrularken kaydettiğiniz Geçiş Bağlantısını otomatik olarak kullanır.

Kod örnekleri

Aşağıdaki kod örneklerinde, Navigation Connect'i kullanarak uygulamanızdan Google Haritalar'ı veya Waze'i nasıl başlatacağınız ve "Uygulamaya dön" düğmesini nasıl etkinleştireceğiniz gösterilmektedir.

Google Haritalar (Android)

Aşağıdaki Kotlin kodu, gerekli parametrelerle bir Navigation Connect oturumu başlatan örnek bir işlevi göstermektedir.

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)

Aşağıdaki Kotlin kodu, gerekli parametrelerle bir Navigation Connect oturumu başlatan örnek bir işlevi göstermektedir.

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)

Aşağıdaki Swift kodu, gerekli parametrelerle bir Navigation Connect oturumu başlatan örnek bir işlevi göstermektedir.

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)
        }
       }