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şleminden 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 olanak tanıyan 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ülerin uygulamanızdan navigasyonu başlatabilmesini sağlamanız gerekir. Sürücülerin bir düğme kullanarak Google Haritalar veya Waze'i başlatmasına izin veriyorsanız uygun ilişkilendirme yapın 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
Bir 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'ine 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
Intentiç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 rotayı başarılı bir şekilde hesaplayabilmesi için hedefinizin biçimlendirmesinde 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.
Seyahat jetonu ve gezinme parametreleri ekleme
Başlatma URL'sini tamamlamak için Seyahat oluşturma 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 zorunlu kılar.external_trip_token: Bu parametre, kimliği doğrulanmış seyahat 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 girin (yalnızca Android)
Navigation Connect ile gezi başlatmak için Android'de bir navigasyon oturumunu uygulamanızla ilişkilendirmeniz gerekir. Bunun için doğrulanmış uygulama kimliğinizi girin. Bu, Google Haritalar veya Waze'in etkin yolculuğu platformunuza geri bağlayabilmesi için uygulamanızı yolculuğun kaynağı olarak tanımlar. Eksik veya geçersiz bir uygulama kimliği, seyahat 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 almaya yetkili 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, anlık 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.
Uygulama kimliğini Android'de Google Haritalar veya Waze'e iletmek için Intent.EXTRA_REFERRER_NAME kullanarak paket adınızı başlatma amaçlı intent'e (başlatma URL'si dizesini taşır) ekleyin.
Aşağıdaki örnekte, paketin adının niyet nesnesine 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 dönen bir PendingIntent oluşturmanız gerekir. Bu PendingIntent öğesini, tam anahtarı "pendingIntent" kullanarak başlatma amaçlı intent'e ek olarak ekleyin. Kullanıcı geri dönme düğmesine dokunduğunda Google Haritalar veya Waze, uygulamanızı ön plana getirmek için bu amaca yönelik işlemi 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 kodunda, gerekli parametrelerle bir Navigation Connect oturumu başlatan örnek bir işlev gösterilmektedir.
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)
}
}