如要啟動導航工作階段，應用程式必須動態建構啟動網址，才能開啟 Google 地圖或 Waze。本指南說明如何使用「建立行程」傳回的已驗證行程權杖，啟動 Google 地圖或 Waze，並設定返回應用程式的體驗。
如何啟動 Google 地圖或 Waze
如要啟動 Google 地圖或 Waze，您必須提供方法，讓駕駛人從應用程式啟動導航工作階段、使用必要參數建構啟動網址，並提供應用程式 ID 來歸因工作階段。
讓駕駛人從您的應用程式啟動導航
您應提供方法，讓駕駛人從應用程式啟動導航。如果允許駕駛人使用按鈕啟動 Google 地圖或 Waze，請務必清楚標示，確保屬性正確，避免造成混淆。例如，將「Google 地圖」或「Waze」文字放在按鈕上或附近。
建構啟動網址
如要啟動導覽工作階段，請建構 Navigation Connect 啟動網址。這個網址是包含目的地、行程權杖和必要導航參數的字串。這與標準 Google 地圖網址或 Waze 深層連結的運作方式類似。
如要在駕駛人的裝置上啟動 Google 地圖或 Waze，請使用平台專屬機制：
- Android：在
Intent中傳遞網址字串。 - iOS：將網址字串做為通用連結 (或深層連結) 使用。
設定目的地格式
為確保 Google 地圖或 Waze 能順利計算路線，請遵守下列目的地格式規則：
請指定一個可連線的到達網頁。您可以將目的地傳遞為地址字串、經緯度座標或地點 ID。
請勿使用多個中途點。如果直接在網址中傳遞多個中途點，Google 地圖或 Waze 會顯示錯誤。請改為建立個別行程。
新增行程權杖和導覽參數
如要完成啟動網址，請務必加入您從「建立行程」要求收到的已驗證行程權杖。您也必須加入導航參數，告知 Google 地圖或 Waze 啟動導航。
Google 地圖
如果是 Google 地圖，請在啟動網址中加入下列參數：
dir_action=navigate：這個參數會強制啟動導航。action_token：這個參數會提供通過驗證的行程權杖。
以下範例說明如何使用不同目的地格式，設定 Google 地圖的啟動網址：
-
經緯度座標：
https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN
-
地址字串：
https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN
-
地點 ID：
https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN
Waze
如果是 Waze，請在啟動網址中加入下列參數：
navigate=yes：這個參數會強制啟動導航。external_trip_token：這個參數會提供通過驗證的行程權杖。
以下範例說明如何使用不同的目的地格式，設定 Waze 的啟動網址：
-
經緯度座標：
https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN
-
地址字串：
https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN
-
地點 ID：
https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN
提供應用程式 ID (僅限 Android)
如要在 Android 上將導覽工作階段歸因於應用程式，請提供已驗證的應用程式 ID。這項 ID 會將您的應用程式識別為行程來源，讓 Google 地圖或 Waze 將進行中的行程連結回您的平台。
提供應用程式 ID 可啟用下列功能：
- 授權資料共用：驗證應用程式是否已獲授權接收進行中行程資料。
- 啟用駕駛人同意聲明：在同意聲明畫面中填入貴商家名稱和隱私權政策，確保駕駛人瞭解誰會收到他們的即時位置和預計抵達時間。
- 啟用返回按鈕：讓 Google 地圖或 Waze 建立品牌返回按鈕，方便駕駛人切換回您的應用程式。
如要在 Android 上將應用程式 ID 傳遞至 Google 地圖或 Waze，請使用 Intent.EXTRA_REFERRER_NAME 將套件名稱新增至啟動意圖 (其中包含啟動網址字串)。
以下範例說明如何在 Intent 中新增套件名稱：
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
如何讓司機返回應用程式
Navigation Connect 會顯示底部列 (Google 地圖) 或品牌返回按鈕 (Waze)，讓駕駛在行程期間或抵達目的地時，隨時都能順暢切換回您的應用程式。
Android
您必須建立 PendingIntent，指回應用程式的活動。使用確切的鍵 "pendingIntent"，將這個 PendingIntent 做為額外內容附加至啟動意圖。使用者輕觸返回按鈕時，Google 地圖或 Waze 會執行這項意圖，將您的應用程式帶到前景。
intent.putExtra("pendingIntent", getPendingIntent())iOS (僅限 Waze)
如要啟用返回按鈕，不必在啟動網址中加入任何內容。Waze 會自動使用您驗證應用程式時註冊的通用連結。
程式碼範例
下列程式碼範例說明如何使用 Navigation Connect 從應用程式啟動 Google 地圖或 Waze，並啟用「返回應用程式」按鈕。
Google 地圖 (Android)
下列 Kotlin 程式碼顯示範例函式，該函式會使用必要參數啟動 Navigation Connect 工作階段。
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)
下列 Kotlin 程式碼顯示範例函式，該函式會使用必要參數啟動 Navigation Connect 工作階段。
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)
下列 Swift 程式碼顯示範例函式，可使用必要參數啟動 Navigation Connect 工作階段。
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)
}
}