启动 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 地图

对于 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
  • 地点 ID： 
    https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN

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

如需在 Android 上将导航会话归因于您的应用，请提供经过验证的应用 ID。这会将您的应用标识为行程的来源，以便 Google 地图或 Waze 将主动行程链接回您的平台。

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

  • 授权数据共享： 验证您的应用是否已获授权接收主动行程数据。
  • 启用司机同意： 在权限请求页面中填充您的商家名称和隐私权政策，确保司机知道谁在接收他们的实时位置信息和预计到达时间。
  • 启用返回按钮： 使 Google 地图或 Waze 能够构建品牌返回按钮，以便司机切换回您的应用。

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

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

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

如何让司机返回到您的应用

Google 地图应用，底部栏包含返回按钮、应用名称和数据共享图标（位于左侧）。Waze 应用，右侧显示了带有品牌的返回按钮。

Navigation Connect 会显示底部栏（Google 地图）或品牌返回按钮 (Waze)，以便司机在行程期间的任何时间或到达目的地时无缝切换回您的应用。

Android

您必须创建一个 PendingIntent，以指向您的 应用中的 activity。使用确切的键 "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)
        }
       }