Khởi chạy Google Maps hoặc Waze

Để bắt đầu phiên đi theo chỉ dẫn, ứng dụng của bạn phải tự động tạo 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 trong phần Tạo chuyến đ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 chạy Google Maps hoặc Waze

Để 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 một 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 để phân bổ phiên.

Cho phép tài xế bắt đầu đi theo chỉ dẫn trong ứng dụng của bạn

Bạn nên cung cấp một cách để tài xế bắt đầu đi theo chỉ dẫn từ ứng dụng của bạn. Nếu bạn cho phép tài xế chạy Google Maps hoặc Waze bằng một nút, hãy đảm bảo ghi nhận tác giả đú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 một phiên đi theo chỉ dẫn, hãy tạo một URL khởi chạy Navigation Connect. URL này là một chuỗi chứa điểm đến, mã thông báo chuyến đi và các tham số điều hướng bắt buộc. Đường liên kết này hoạt động tương tự như URL Google Maps hoặc Đường liên kết sâu của Waze thông thường.

Để 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 tuyến đường thành công, hãy tuân thủ các quy tắc sau khi định dạng điểm đến:

  • Chỉ định chính xác một đích đến có thể truy cập được. Bạn có thể truyền điểm đến dưới dạng chuỗi địa chỉ, toạ độ vĩ độ/kinh độ hoặc Mã địa điểm.

  • Đừng sử dụng nhiều điểm tham chiếu. Nếu bạn truyền trực tiếp nhiều điểm tham chiếu 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ố điều hướ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 để yêu cầu Google Maps hoặc Waze 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 phải điều hướng chủ động.
  • action_token: Tham số này cung cấp mã thông báo chuyến đi đã xác thực của bạn.

Các ví dụ sau đây cho thấy 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 phải có trong chế độ chỉ đường đang hoạt động.
  • external_trip_token: Tham số này cung cấp mã thông báo chuyến đi đã xác thực của bạn.

Các ví dụ sau đây cho thấy cách định dạng URL khởi chạy cho Waze bằng cách sử dụng các định dạng đích đến khác nhau:

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

Để bắt đầu một chuyến đi bằng Navigation Connect, bạn phải chỉ định một phiên chỉ đường cho ứng dụng của mình trên Android. Để làm việc này, hãy cung cấp mã ứng dụng đã xác minh của bạn. Thông tin 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 với nền tảng của bạn. Mã ứng dụng bị thiếu hoặc không hợp lệ sẽ khiến quá trình xác thực mã thông báo chuyến đi không thành công.

Khi cung cấp mã ứng dụng, bạn có thể sử dụng các tính năng sau:

  • Uỷ quyền chia sẻ dữ liệu: Xác minh rằng ứng dụng của bạn được uỷ quyền 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 thông tin về vị trí theo thời gian thực và thời gian đế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 để người lái xe có thể chuyển về ứng dụng của bạn.

Để truyền mã ứng dụng đến Google Maps hoặc Waze trên Android, hãy thêm tên gói vào ý định khởi chạy (mang chuỗi URL khởi chạy) bằng cách sử dụng Intent.EXTRA_REFERRER_NAME.

Ví dụ sau đây cho thấy 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

Ứng dụng Google Maps có thanh dưới cùng chứa nút quay lại, tên ứng dụng và biểu tượng chia sẻ dữ liệu ở bên trái. Ứng dụng Waze có nút quay lại mang thương hiệu, ở bên phải.

Navigation Connect hiển thị một thanh dưới cùng (Google Maps) hoặc nút quay lại có thương hiệu (Waze) để người lái xe có thể chuyển đổi liền mạch về ứng dụng của bạn tại bất kỳ thời điểm nào trong chuyến đi hoặc khi họ đến điểm đến.

Android

Bạn phải tạo một PendingIntent trỏ về hoạt động của ứng dụng. Đính kèm PendingIntent này dưới dạng một 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ỉ dành cho Waze)

Bạn không cần thêm bất cứ thông tin nào vào URL khởi chạy để bật nút quay lại. Waze tự động sử dụng Đường liên kết phổ quát mà bạn đã đăng ký khi xác minh ứng dụng.

Mã mẫu

Các mã mẫu sau đây cho biết cách 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)
        }
       }