Để bắt đầu phiên chỉ đường, ứng dụng của bạn phải tạo động một URL khởi chạy để mở Google Maps hoặc Waze. Hướng dẫn này mô tả cách sử dụng mã thông báo chuyến đi đã xác thực từ Tạo chuyến đi để khởi chạy Google Maps hoặc Waze và định cấu hình trải nghiệm quay lại ứng dụng của bạn.
Cách khởi chạy Google Maps hoặc Waze
Để khởi chạy Google Maps hoặc Waze, bạn phải cung cấp một cách để cho phép tài xế bắt đầu phiên chỉ đường từ ứng dụng của bạn, tạo URL khởi chạy bằng các tham số bắt buộc và cung cấp mã ứng dụng của bạn để phân bổ phiên.
Cho phép tài xế bắt đầu chỉ đường từ ứng dụng của bạn
Bạn nên cung cấp một cách để tài xế bắt đầu chỉ đường từ ứng dụng của bạn. Nếu bạn cho phép tài xế khởi chạy Google Maps hoặc Waze bằng một nút, hãy đảm bảo phân bổ đúng cách và tránh gây nhầm lẫn bằng cách gắn nhãn rõ ràng. Ví dụ: đặt văn bản "Google Maps" hoặc "Waze" trên hoặc gần nút.
Tạo URL khởi chạy
Để bắt đầu phiên chỉ đường, hãy tạo URL khởi chạy Navigation Connect. URL này là một chuỗi chứa đích đến, mã thông báo chuyến đi và các tham số chỉ đường bắt buộc. URL này hoạt động tương tự như URL Google Maps tiêu chuẩn hoặc Đường liên kết sâu của Waze.
Để khởi chạy Google Maps hoặc Waze trên thiết bị của tài xế, hãy sử dụng cơ chế dành riêng cho nền tảng:
- Android: Truyền chuỗi URL trong
Intent. - iOS: Sử dụng chuỗi URL làm Đường liên kết phổ quát (hoặc đường liên kết sâu).
Định dạng đích đến
Để đảm bảo Google Maps hoặc Waze có thể tính toán thành công một tuyến đường, hãy tuân thủ các quy tắc sau khi định dạng đích đến:
Chỉ định chính xác một đích đến có thể tiếp cận. Bạn có thể truyền đích đến dưới dạng chuỗi địa chỉ, toạ độ vĩ độ/kinh độ hoặc mã địa điểm.
Không sử dụng nhiều điểm dừng. Nếu bạn truyền trực tiếp nhiều điểm dừng trong URL, Google Maps hoặc Waze sẽ hiển thị lỗi. Thay vào đó, hãy tạo các chuyến đi riêng biệt.
Thêm mã thông báo chuyến đi và tham số chỉ đường
Để hoàn tất URL khởi chạy, bạn phải thêm mã thông báo chuyến đi đã xác thực mà bạn nhận được từ yêu cầu Tạo chuyến đi. Bạn cũng phải thêm các tham số chỉ đường cho Google Maps hoặc Waze biết để bắt đầu chỉ đường.
Google Maps
Đối với Google Maps, hãy thêm các tham số sau vào URL khởi chạy:
dir_action=navigate: Tham số này buộc chỉ đường.action_token: Tham số này cung cấp mã thông báo chuyến đi đã xác thực.
Các ví dụ sau đây cho biết cách định dạng URL khởi chạy cho Google Maps bằng nhiều định dạng đích đến:
-
Toạ độ vĩ độ/kinh độ:
https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN
-
Chuỗi địa chỉ:
https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN
-
Mã địa điểm:
https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN
Waze
Đối với Waze, hãy thêm các tham số sau vào URL khởi chạy:
navigate=yes: Tham số này buộc chỉ đường.external_trip_token: Tham số này cung cấp mã thông báo chuyến đi đã xác thực.
Các ví dụ sau đây cho biết cách định dạng URL khởi chạy cho Waze bằng nhiều định dạng đích đến:
-
Toạ độ vĩ độ/kinh độ:
https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN
-
Chuỗi địa chỉ:
https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN
-
Mã địa điểm:
https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN
Cung cấp mã ứng dụng (chỉ dành cho Android)
Để phân bổ phiên chỉ đường cho ứng dụng của bạn trên Android, hãy cung cấp mã ứng dụng đã xác minh. Mã này xác định ứng dụng của bạn là nguồn của chuyến đi để Google Maps hoặc Waze có thể liên kết hành trình đang diễn ra trở lại nền tảng của bạn.
Việc cung cấp mã ứng dụng sẽ bật các tính năng sau:
- Cho phép chia sẻ dữ liệu: Xác minh rằng ứng dụng của bạn được phép nhận dữ liệu chuyến đi đang diễn ra.
- Bật tính năng đồng ý của tài xế: Điền tên doanh nghiệp và chính sách quyền riêng tư của bạn vào màn hình xin phép, đảm bảo tài xế biết ai đang nhận vị trí theo thời gian thực và Giờ đến dự kiến của họ.
- Bật nút quay lại: Cho phép Google Maps hoặc Waze tạo nút quay lại có thương hiệu để tài xế có thể chuyển lại ứng dụng của bạn.
Để truyền mã ứng dụng cho Google Maps hoặc Waze trên Android, hãy thêm tên gói vào ý định khởi chạy (chứa chuỗi URL khởi chạy) bằng Intent.EXTRA_REFERRER_NAME.
Ví dụ sau đây cho biết cách thêm tên gói vào ý định:
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
Cách cho phép tài xế quay lại ứng dụng của bạn
Navigation Connect hiển thị một thanh dưới cùng (Google Maps) hoặc một nút quay lại có thương hiệu (Waze) để tài xế có thể chuyển lại ứng dụng của bạn một cách liền mạch vào bất kỳ thời điểm nào trong chuyến đi hoặc khi họ đến đích.
Android
Bạn phải tạo một PendingIntent trỏ lại hoạt động của ứng dụng. Đính kèm PendingIntent này dưới dạng phần bổ sung vào ý định khởi chạy
bằng cách sử dụng chính xác khoá "pendingIntent". Khi người dùng nhấn vào nút quay lại, Google Maps hoặc Waze sẽ thực thi ý định này để đưa ứng dụng của bạn lên nền trước.
intent.putExtra("pendingIntent", getPendingIntent())iOS (chỉ Waze)
Bạn không cần thêm bất cứ nội dung nào vào URL khởi chạy để bật nút quay lại. Waze sẽ tự động sử dụng Đường liên kết phổ quát mà bạn đã đăng ký khi bạn xác minh ứng dụng của mình.
Mã mẫu
Các mẫu mã sau đây cho biết cách khởi chạy Google Maps hoặc Waze từ ứng dụng của bạn bằng Navigation Connect và bật nút "Quay lại ứng dụng".
Google Maps (Android)
Mã Kotlin sau đây cho thấy một hàm mẫu khởi chạy phiên Navigation Connect với các tham số bắt buộc.
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)
Mã Kotlin sau đây cho thấy một hàm mẫu khởi chạy phiên Navigation Connect với các tham số bắt buộc.
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)
Mã Swift sau đây cho thấy một hàm mẫu khởi chạy phiên Navigation Connect với các tham số bắt buộc.
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)
}
}