หากต้องการเริ่มเซสชันการนำทาง แอปของคุณต้องสร้าง URL การเปิดแบบไดนามิกเพื่อเปิด Google Maps หรือ Waze คู่มือนี้อธิบายวิธีใช้โทเค็นการเดินทางที่ตรวจสอบสิทธิ์แล้วจากสร้างการเดินทางเพื่อเปิด Google Maps หรือ Waze และกำหนดค่าประสบการณ์การกลับไปยังแอปของคุณ
วิธีเปิด Google Maps หรือ Waze
หากต้องการเปิด Google Maps หรือ Waze คุณต้องระบุวิธีที่ช่วยให้คนขับเริ่มเซสชันการนำทางจากแอปของคุณ สร้าง URL การเปิดแอปพร้อมพารามิเตอร์ที่จำเป็น และระบุรหัสแอปพลิเคชันเพื่อระบุแหล่งที่มาของเซสชัน
อนุญาตให้คนขับเริ่มการนำทางจากแอปของคุณ
คุณควรจัดเตรียมวิธีให้คนขับเริ่มการนำทางจากแอปของคุณ หากคุณอนุญาตให้คนขับเปิด Google Maps หรือ Waze โดยใช้ปุ่ม ให้ตรวจสอบว่ามีการระบุแหล่งที่มาอย่างเหมาะสมและหลีกเลี่ยงความสับสนโดยติดป้ายกำกับอย่างชัดเจน เช่น วางข้อความ "Google Maps" หรือ "Waze" ไว้บนหรือใกล้กับปุ่ม
สร้าง URL สำหรับเปิดใช้งาน
หากต้องการเริ่มเซสชันการนำทาง ให้สร้าง URL สำหรับเปิด Navigation Connect URL นี้เป็นสตริงที่มีปลายทาง โทเค็นการเดินทาง และพารามิเตอร์การนำทางที่จำเป็น ซึ่งทำงานคล้ายกับ URL ของ Google Maps หรือ Deep Link ของ Waze แบบมาตรฐาน
หากต้องการเปิด Google Maps หรือ Waze บนอุปกรณ์ของคนขับ ให้ใช้กลไกเฉพาะแพลตฟอร์มดังนี้
- Android: ส่งสตริง URL ใน
Intent - iOS: ใช้สตริง URL เป็น Universal Link (หรือ Deep Link)
จัดรูปแบบปลายทาง
โปรดปฏิบัติตามกฎต่อไปนี้เมื่อจัดรูปแบบจุดหมายเพื่อให้ Google Maps หรือ Waze คำนวณเส้นทางได้สำเร็จ
ระบุปลายทางที่เข้าถึงได้ 1 รายการ คุณสามารถส่งปลายทางเป็นสตริงที่อยู่ พิกัดละติจูด/ลองจิจูด หรือรหัสสถานที่ได้
อย่าใช้จุดอ้างอิงหลายจุด หากคุณส่งจุดอ้างอิงหลายจุดใน URL โดยตรง Google Maps หรือ Waze จะแสดงข้อผิดพลาด แต่ให้สร้างการเดินทางแยกกันแทน
เพิ่มโทเค็นการเดินทางและพารามิเตอร์การนําทาง
หากต้องการสร้าง URL การเปิดให้เสร็จสมบูรณ์ คุณต้องใส่โทเค็นการเดินทางที่ตรวจสอบสิทธิ์แล้วซึ่งได้รับจากคำขอสร้างการเดินทาง นอกจากนี้ คุณต้องใส่พารามิเตอร์การนำทางที่บอกให้ Google Maps หรือ Waze เริ่มการนำทางที่ใช้งานอยู่ด้วย
Google Maps
สำหรับ Google Maps ให้ใส่พารามิเตอร์ต่อไปนี้ใน URL การเปิดใช้งาน
dir_action=navigate: พารามิเตอร์นี้บังคับให้ใช้การนําทางที่ใช้งานอยู่action_token: พารามิเตอร์นี้จะระบุโทเค็นการเดินทางที่ตรวจสอบสิทธิ์แล้ว
ตัวอย่างต่อไปนี้แสดงวิธีจัดรูปแบบ URL การเปิดใช้สำหรับ Google Maps โดยใช้รูปแบบปลายทางที่แตกต่างกัน
-
พิกัดละติจูด/ลองจิจูด:
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
-
รหัสสถานที่:
https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN
Waze
สำหรับ Waze ให้ใส่พารามิเตอร์ต่อไปนี้ใน URL การเปิดใช้งาน
navigate=yes: พารามิเตอร์นี้บังคับให้ใช้การนําทางที่ใช้งานอยู่external_trip_token: พารามิเตอร์นี้จะระบุโทเค็นการเดินทางที่ตรวจสอบสิทธิ์แล้ว
ตัวอย่างต่อไปนี้แสดงวิธีจัดรูปแบบ URL การเปิดใช้งานสำหรับ 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
-
รหัสสถานที่:
https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN
ระบุรหัสแอปพลิเคชัน (Android เท่านั้น)
หากต้องการเริ่มการเดินทางด้วย Navigation Connect คุณต้องระบุแหล่งที่มาของเซสชันการนําทางไปยังแอปของคุณใน Android โดยระบุรหัสแอปพลิเคชันที่ยืนยันแล้ว ซึ่งจะระบุว่าแอปของคุณเป็นแหล่งที่มาของการเดินทาง เพื่อให้ Google Maps หรือ Waze สามารถลิงก์การเดินทางที่ใช้งานอยู่กลับไปยังแพลตฟอร์มของคุณได้ รหัสแอปพลิเคชันที่ขาดหายไปหรือไม่ถูกต้องจะส่งผลให้การตรวจสอบสิทธิ์โทเค็นการเดินทางไม่สำเร็จ
การระบุรหัสแอปพลิเคชันจะเปิดใช้ฟีเจอร์ต่อไปนี้
- ให้สิทธิ์การแชร์ข้อมูล: ยืนยันว่าแอปของคุณได้รับสิทธิ์ให้รับข้อมูลการเดินทางที่ดำเนินอยู่
- เปิดใช้ความยินยอมของคนขับ: แสดงหน้าจอขอความยินยอมพร้อมชื่อธุรกิจและนโยบายความเป็นส่วนตัว เพื่อให้คนขับทราบว่าใครจะได้รับตำแหน่งแบบเรียลไทม์และ ETA ของตน
- เปิดใช้ปุ่มย้อนกลับ: ช่วยให้ Google Maps หรือ Waze สร้างปุ่มย้อนกลับที่มีแบรนด์เพื่อให้ผู้ขับขี่เปลี่ยนกลับไปใช้แอปของคุณได้
หากต้องการส่งรหัสแอปพลิเคชันไปยัง Google Maps หรือ Waze บน Android ให้เพิ่มชื่อแพ็กเกจลงใน Intent การเปิด (ซึ่งมีสตริง URL การเปิด) โดยใช้ Intent.EXTRA_REFERRER_NAME
ตัวอย่างต่อไปนี้แสดงวิธีเพิ่มชื่อแพ็กเกจลงใน Intent
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
วิธีอนุญาตให้คนขับกลับไปที่แอปของคุณ
Navigation Connect จะแสดงแถบด้านล่าง (Google Maps) หรือปุ่มย้อนกลับที่มีแบรนด์ (Waze) เพื่อให้คนขับเปลี่ยนกลับไปใช้แอปของคุณได้อย่างราบรื่น ณ จุดใดก็ได้ระหว่างการเดินทางหรือเมื่อถึงจุดหมาย
Android
คุณต้องสร้าง PendingIntent ที่ชี้กลับไปยังกิจกรรมของแอป แนบ PendingIntent นี้เป็นส่วนเสริมให้กับ Intent การเปิดตัวโดยใช้คีย์ "pendingIntent" ที่ตรงกันทุกประการ เมื่อผู้ใช้แตะปุ่มย้อนกลับ Google Maps หรือ Waze จะเรียกใช้ Intent นี้เพื่อนำแอปของคุณมาไว้ที่เบื้องหน้า
intent.putExtra("pendingIntent", getPendingIntent())iOS (Waze เท่านั้น)
คุณไม่จำเป็นต้องเพิ่มสิ่งใดลงใน URL การเปิดใช้งานเพื่อเปิดใช้ปุ่มย้อนกลับ Waze จะใช้ Universal Link ที่คุณลงทะเบียนไว้เมื่อยืนยันแอปโดยอัตโนมัติ
ตัวอย่างโค้ด
ตัวอย่างโค้ดต่อไปนี้แสดงวิธีเปิด Google Maps หรือ Waze จากแอปของคุณโดยใช้ Navigation Connect และเปิดใช้ปุ่ม "กลับไปที่แอป"
Google Maps (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)
}
}