เปิด Google Maps หรือ Waze

หากต้องการเริ่มเซสชันการนำทาง แอปของคุณต้องสร้าง URL การเปิดใช้แบบไดนามิกเพื่อเปิด Google Maps หรือ Waze คู่มือนี้อธิบาย วิธีใช้โทเค็นการเดินทางที่ผ่านการตรวจสอบสิทธิ์จาก Create a trip เพื่อ เปิด 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 คำนวณเส้นทางได้สำเร็จ ให้ปฏิบัติตามกฎต่อไปนี้เมื่อจัดรูปแบบปลายทาง

  • ระบุปลายทางที่เข้าถึงได้เพียงแห่งเดียว คุณสามารถส่งปลายทางเป็นสตริงที่อยู่ พิกัดละติจูด/ลองจิจูด หรือรหัสสถานที่

  • อย่าใช้จุดแวะหลายจุด หากคุณส่งจุดแวะหลายจุดใน URL โดยตรง Google Maps หรือ Waze จะแสดงข้อผิดพลาด ให้สร้างการเดินทางแยกกันแทน

เพิ่มโทเค็นการเดินทางและพารามิเตอร์การนำทาง

หากต้องการสร้าง URL การเปิดใช้ให้สมบูรณ์ คุณต้องใส่โทเค็นการเดินทางที่ผ่านการตรวจสอบสิทธิ์ที่ คุณได้รับจากคำขอ Create a trip นอกจากนี้ คุณต้องใส่พารามิเตอร์การนำทางที่บอกให้ 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 เท่านั้น)

หากต้องการระบุแหล่งที่มาของเซสชันการนำทางเป็นแอปของคุณใน Android ให้ระบุรหัสแอปพลิเคชันที่ยืนยันแล้ว ซึ่งจะระบุแอปของคุณเป็นแหล่งที่มาของการเดินทางเพื่อให้ Google Maps หรือ Waze ลิงก์การเดินทางที่ใช้งานอยู่กลับไปยังแพลตฟอร์มของคุณได้

การระบุรหัสแอปพลิเคชันจะเปิดใช้ฟีเจอร์ต่อไปนี้

  • ให้สิทธิ์การแชร์ข้อมูล: ยืนยันว่าแอปของคุณได้รับอนุญาตให้รับข้อมูลการเดินทางที่ใช้งานอยู่
  • เปิดใช้ความยินยอมของคนขับ: ป้อนชื่อธุรกิจและนโยบายความเป็นส่วนตัวในหน้าจอขอความยินยอม เพื่อให้คนขับทราบว่าใครเป็นผู้รับตำแหน่งแบบเรียลไทม์และเวลาที่คาดว่าจะถึง
  • เปิดใช้ปุ่มกลับ: ช่วยให้ Google Maps หรือ Waze สร้างปุ่มกลับที่มีการใส่แบรนด์เพื่อให้คนขับกลับไปที่แอปของคุณได้

หากต้องการส่งรหัสแอปพลิเคชันไปยัง Google Maps หรือ Waze ใน Android ให้เพิ่มชื่อแพ็กเกจลงใน Intent การเปิดใช้ (ซึ่งมีสตริง URL การเปิดใช้) โดยใช้ Intent.EXTRA_REFERRER_NAME

ตัวอย่างต่อไปนี้แสดงวิธีเพิ่มชื่อแพ็กเกจลงใน Intent

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

วิธีให้คนขับกลับไปที่แอปของคุณ

แอป Google Maps ที่มีแถบด้านล่างซึ่งมีปุ่มย้อนกลับ ชื่อแอป และไอคอนการแชร์ข้อมูลทางด้านซ้าย แอป Waze ที่มีปุ่มย้อนกลับของแบรนด์ทางด้านขวา

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