เปิด Google Maps หรือ Waze

หากต้องการเริ่มเซสชันการนำทาง แอปของคุณต้องสร้าง 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 เท่านั้น)

หากต้องการระบุแหล่งที่มาของเซสชันการนำทางไปยังแอปใน 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)
        }
       }