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

Để 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 trả về cho ứ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 người lái xe bắt đầu một phiên điều hướ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 người lái xe bắt đầu chỉ đường từ ứng dụng của bạn

Bạn nên cung cấp cho người lái xe một cách để bắt đầu chế độ dẫn đường từ ứng dụng của bạn. Nếu bạn cho phép người lái xe khởi chạy Google Maps hoặc Waze bằng một nút, hãy đảm bảo ghi nhận nguồn đóng góp đúng cách và tránh gây nhầm lẫn bằng cách gắn nhãn rõ ràng cho nút đó. 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 chỉ đường, hãy tạo một 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ố điều hướng bắt buộc. URL này hoạt động tương tự như một URL chuẩn của Google Maps hoặc Đường liên kết sâu của Waze.

Lưu ý quan trọng: Navigation Connect chỉ hỗ trợ chế độ lái xe. Đừng định cấu hình các chế độ di chuyển không phải lái xe (chẳng hạn như đi bộ, đi xe đạp hoặc phương tiện công cộng) trong URL khởi chạy. Nếu người lái xe điều hướng ở chế độ không lái xe, Navigation Connect sẽ không trả về thông tin cập nhật về đo từ xa hoặc thông tin giao thông.

Để chạy Google Maps hoặc Waze trên thiết bị của người lái xe, hãy sử dụng cơ chế dành riêng cho nền tảng:

• Android: Truyền chuỗi URL trong một 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. 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.

• Đừng sử dụng nhiều điểm tham chiếu. Nếu bạn truyền nhiều điểm tham chiếu trực tiếp 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.

Lưu ý: Đừng truyền nguồn gốc bắt đầu tuỳ chỉnh trong URL khởi chạy. Google Maps hoặc Waze sẽ tự động sử dụng vị trí hiện tại của người lái xe khi phiên bắt đầu. Để ngăn lỗi "Không tìm thấy nguồn gốc", hãy yêu cầu tài xế bật tính năng theo dõi vị trí chính xác.

Thêm mã thông báo chuyến đi và các 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ố điều hướng để yêu cầu Google Maps hoặc Waze bắt đầu chế độ chỉ đường 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ế độ chỉ đường đang hoạt độ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 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 minh hoạ 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

  Lưu ý: Waze sẽ điều hướng đến kết quả tìm kiếm đầu tiên cho chuỗi địa chỉ.
• 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 của bạn (chỉ dành cho Android)

Để phân bổ một 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. Tham số 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 hoạt động trở lại nền tảng của bạn.

Lưu ý: Đối với iOS, bạn phải cung cấp mã ứng dụng trong thông báo CreateTripRequest. Hãy xem bài viết Tạo chuyến đi để biết thông tin chi tiết.

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 phép nhận dữ liệu chuyến đi đang diễn ra.
• Bật chế độ đồng ý của người lái xe: Đ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 người lái xe biết ai đang nhận được 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 một nút quay lại có gắn thương hiệu để người lái xe có thể chuyển về ứng dụng của bạn.

Để truyền mã nhận dạng ứ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 (chứa chuỗi URL khởi chạy) bằng cách sử dụ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 nút quay lại có gắn thương hiệu (Waze) để người lái xe có thể chuyển đổi liền mạch trở lại ứng dụng của bạn bất kỳ lúc nào trong chuyến đi hoặc khi họ đến đích.

Android

Bạn phải tạo một PendingIntent trỏ ngược lại 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ứ nội dung 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ẫ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)

Đoạn mã Kotlin sau đây cho thấy một hàm mẫu khởi chạy phiên Navigation Connect bằng 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)

Đoạn mã Kotlin sau đây cho thấy một hàm mẫu khởi chạy phiên Navigation Connect bằng 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)

Đoạn mã Swift sau đây cho thấy một hàm mẫu khởi chạy phiên Navigation Connect bằng 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)
        }
       }