Google Haritalar veya Waze'i başlatma

Navigasyon oturumunu başlatmak için uygulamanızın Google Haritalar veya Waze'i açacak bir başlatma URL'si oluşturması gerekir. Bu kılavuzda, Seyahat oluşturma işlevinden alınan kimliği doğrulanmış seyahat jetonunu kullanarak Google Haritalar veya Waze'i başlatma ve geri dönüş deneyimini uygulamanıza yönlendirecek şekilde yapılandırma 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 bir navigasyon oturumu başlatmasına izin verecek bir yöntem sağlamanız, başlatma URL'sini gerekli parametrelerle oluşturmanız ve oturumu ilişkilendirmek için uygulama kimliğinizi göndermeniz gerekir.

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

Sürücülere uygulamanızdan navigasyonu başlatma olanağı sunmanız gerekir. Sürücülerin bir düğme kullanarak Google Haritalar veya Waze'i başlatmasına izin veriyorsanız uygun ilişkilendirme yaptığınızdan emin olun ve düğmeyi net bir şekilde etiketleyerek karışıklığı önleyin. Örneğin, "Google Haritalar" veya "Waze" metnini düğmenin üzerine ya da yakınına yerleştirin.

Başlatma URL'sini oluşturma

Navigasyon oturumu başlatmak için Navigation Connect başlatma URL'si oluşturun. Bu URL, hedefi, gezi jetonunu ve gerekli gezinme parametrelerini içeren bir dizedir. Standart bir Google Haritalar URL'si veya Waze Deep Link'e 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 Intent içinde iletin.
• iOS: URL dizesini Evrensel Bağlantı (veya derin bağlantı) olarak kullanın.

Hedefi biçimlendirme

Google Haritalar veya Waze'in rotayı başarıyla hesaplayabilmesi için hedefinizin biçimlendirilmesinde aşağıdaki kurallara uyun:

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

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

Not: Başlatma URL'sinde özel bir başlangıç kaynağı iletmeyin. Google Haritalar veya Waze, oturum başladığında sürücünün mevcut konumunu otomatik olarak kullanır. "Kaynak bulunamadı" hatalarını önlemek için sürücülerinizin hassas konum takibini etkinleştirmesini zorunlu kılın.

Seyahat jetonu ve gezinme parametreleri ekleme

Başlatma URL'sini tamamlamak için Seyahat oluştur isteğinden aldığınız kimliği doğrulanmış seyahat jetonunu eklemeniz gerekir. Google Haritalar veya Waze'e aktif 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 gezinmeyi zorunlu kılar.
• action_token: Bu parametre, kimliği doğrulanmış seyahat 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 gezinmeyi zorlar.
• external_trip_token: Bu parametre, kimliği doğrulanmış seyahat jetonunuzu sağlar.

Aşağıdaki örneklerde, farklı hedef biçimlerini 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

  Not: Waze, adres dizeleri için ilk arama sonucuna gider.
• Yer kimliği:

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

Uygulama kimliğinizi girin (yalnızca Android)

Android'de bir gezinme oturumunu uygulamanızla ilişkilendirmek için doğrulanmış uygulama kimliğinizi sağlayın. Bu, Google Haritalar veya Waze'in etkin yolculuğu platformunuza geri bağlayabilmesi için uygulamanızı yolculuğun kaynağı olarak tanımlar.

Not: iOS için uygulama kimliğini CreateTripRequest mesajında belirtmiş olmanız gerekir. Ayrıntılı bilgi için Seyahat oluşturma başlıklı makaleyi inceleyin.

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 yetkisine sahip olduğunu doğrular.
• Sürücü iznini etkinleştirme: İzin ekranını işletme adınız ve gizlilik politikanızla doldurarak sürücünün gerçek zamanlı konumunu ve tahmini varış zamanını kimin aldığını bilmesini sağlar.
• Geri dön düğmesini etkinleştirin: Google Haritalar veya Waze'in markalı bir geri dön düğmesi oluşturmasını sağlar. Böylece sürücüler uygulamanıza geri dönebilir.

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

Aşağıdaki örnekte, paketin adının amaca nasıl ekleneceği gösterilmektedir:

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

Sürücülerin uygulamanıza geri dönmesini sağlama

Navigation Connect, sürücünün yolculuk sırasında veya hedefe vardığında uygulamanıza sorunsuz bir şekilde geri dönebilmesi için alt çubuk (Google Haritalar) ya da markalı bir geri düğmesi (Waze) gösterir.

Android

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

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

iOS (yalnızca Waze)

Geri dön düğmesini etkinleştirmek için lansman URL'sine herhangi bir şey eklemeniz gerekmez. Waze, uygulamanızı doğruladığınızda 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 başlatma ve "Uygulamaya dön" düğmesini etkinleştirme gösterilmektedir.

Google Haritalar (Android)

Aşağıdaki Kotlin kodunda, gerekli parametrelerle bir Navigation Connect oturumu başlatan örnek bir işlev gösterilmektedir.

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 kodunda, gerekli parametrelerle bir Navigation Connect oturumu başlatan örnek bir işlev gösterilmektedir.

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österir.

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