启动 Google 地图或 Waze

若要启动导航会话，您的应用必须动态构建启动网址以打开 Google 地图或 Waze。本指南介绍了如何使用创建行程中的经过身份验证的行程令牌来启动 Google 地图或 Waze，以及如何配置返回到您应用的体验。

如何启动 Google 地图或 Waze

如需启动 Google 地图或 Waze，您必须提供一种方式，让司机能够从您的应用中开始导航会话，使用必需的参数构建启动网址，并提供您的应用 ID 以归因会话。

允许司机从您的应用中启动导航

您应提供一种方式，让司机能够从您的应用中开始导航。如果您允许司机使用按钮启动 Google 地图或 Waze，请确保提供适当的提供方信息，并通过清晰的标签避免混淆。例如，将“Google 地图”或“Waze”文字放在按钮上或附近。

构建启动网址

如需启动导航会话，请构建 Navigation Connect 启动网址。此网址是一个字符串，其中包含目的地、行程令牌和必需的导航参数。其功能与标准 Google 地图网址或 Waze 深层链接类似。

如需在司机的设备上启动 Google 地图或 Waze，请使用特定于平台的机制：

• Android：在 Intent 中传递网址字符串。
• iOS：将网址字符串用作通用链接（或深层链接）。

设置目标格式

为确保 Google 地图或 Waze 能够成功计算路线，请在设置目的地格式时遵循以下规则：

• 指定一个可到达的目标位置。您可以将目的地作为地址字符串、纬度/经度坐标或地点 ID 传递。

• 请勿使用多个途经点。如果您直接在网址中传递多个途经点，Google 地图或 Waze 会显示错误。请改为创建单独的行程。

注意： 请勿在启动网址中传递自定义起始来源。Google 地图或 Waze 会在会话开始时自动使用驾驶员的当前位置。为防止出现“找不到出发地”错误，请要求司机启用精确定位跟踪。

添加行程令牌和导航参数

如需完成启动网址，您必须添加从创建行程请求中收到的经过身份验证的行程令牌。您还必须添加导航参数，以告知 Google 地图或 Waze 开始主动导航。

Google 地图

对于 Google 地图，请在启动网址中添加以下参数：

• dir_action=navigate：此参数会强制执行主动导航。
• action_token：此参数提供经过身份验证的行程令牌。

以下示例展示了如何使用不同的目的地格式设置 Google 地图启动网址的格式：

• 经纬度坐标：

  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

• 地点 ID：

  https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN

Waze

对于 Waze，请在启动网址中添加以下参数：

• navigate=yes：此参数会强制执行主动导航。
• external_trip_token：此参数用于提供经过身份验证的行程令牌。

以下示例展示了如何使用不同的目的地格式设置 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

  注意：Waze 会导航到地址字符串的第一个搜索结果。
• 地点 ID：

  https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN

提供您的应用 ID（仅限 Android）

如需在 Android 上将导航会话归因于您的应用，请提供经过验证的应用 ID。此参数用于将您的应用标识为行程的来源，以便 Google 地图或 Waze 将正在进行的行程关联回您的平台。

注意： 对于 iOS，您应该已在 CreateTripRequest 消息中提供了应用 ID。如需了解详情，请参阅创建行程。

提供应用 ID 可启用以下功能：

• 授权数据共享：验证您的应用是否已获得接收有效行程数据的授权。
• 启用驾驶员同意声明：在同意声明界面中预先填充您的商家名称和隐私权政策，确保驾驶员知道谁会接收其实时位置信息和预计到达时间。
• 启用返回按钮：使 Google 地图或 Waze 能够构建品牌化的返回按钮，以便司机切换回您的应用。

如需在 Android 上将应用 ID 传递给 Google 地图或 Waze，请使用 Intent.EXTRA_REFERRER_NAME 将软件包名称添加到启动 intent（其中包含启动网址字符串）。

以下示例展示了如何将软件包名称添加到 intent 中：

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

如何让司机返回您的应用

Navigation Connect 会显示底部栏（Google 地图）或带有品牌的返回按钮 (Waze)，以便司机在旅途中的任何时间或到达目的地时都能顺畅地切换回您的应用。

Android

您必须创建一个指向应用 activity 的 PendingIntent。使用确切的键 "pendingIntent" 将此 PendingIntent 作为 extra 附加到启动 intent。当用户点按返回按钮时，Google 地图或 Waze 会执行此 intent，将您的应用置于前台。

intent.putExtra("pendingIntent", getPendingIntent())

iOS（仅限 Waze）

您无需向启动网址添加任何内容即可启用返回按钮。Waze 会在您验证应用时自动使用您注册的通用链接。

代码示例

以下代码示例展示了如何使用 Navigation Connect 从应用启动 Google 地图或 Waze，并启用“返回应用”按钮。

Google 地图 (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)
        }
       }