Запустите Google Карты или Waze.

Чтобы начать сеанс навигации, ваше приложение должно динамически создать URL запуска для открытия Google Карт или Waze. В этом руководстве описывается, как использовать токен аутентифицированной поездки, полученный на этапе Создание поездки, чтобы запустить Google Карты или Waze и настроить возврат в ваше приложение.

Как запустить Google Карты или Waze

Чтобы запустить Google Карты или Waze, вам нужно предоставить водителям возможность начать сеанс навигации из вашего приложения, создать URL запуска с необходимыми параметрами и указать идентификатор приложения, чтобы связать его с сеансом.

Как разрешить водителям запускать навигацию из вашего приложения

В вашем приложении должна быть возможность запустить навигацию. Если вы добавите кнопку, которая открывает Google Карты или Waze, не забудьте указать, что это за сервис, чтобы не запутать водителей. Например, разместите на кнопке или рядом с ней текст "Google Карты" или "Waze".

Как создать URL для запуска

Чтобы начать сеанс навигации, создайте URL запуска Navigation Connect. Этот URL представляет собой строку, содержащую пункт назначения, токен поездки и необходимые параметры навигации. Она работает так же, как стандартный URL Google Карт или ссылка на контент в Waze.

Чтобы запустить Google Карты или Waze на устройстве водителя, используйте механизм, предназначенный для конкретной платформы:

  • Android. Передайте строку URL в Intent.
  • iOS. Используйте строку URL в качестве универсальной ссылки (или ссылки на контент).

Формат целевого сервиса

Чтобы Google Карты или Waze могли рассчитать маршрут, при форматировании пункта назначения соблюдайте следующие правила:

  • Укажите ровно один доступный пункт назначения. Пункт назначения можно передать в виде строки адреса, координат широты и долготы или идентификатора места.

  • Не используйте несколько путевых точек. Если вы передадите несколько путевых точек непосредственно в URL, Google Карты или Waze покажут ошибку. Вместо этого создайте отдельные поездки.

Добавьте токен поездки и параметры навигации

Чтобы завершить URL запуска, необходимо включить токен аутентифицированной поездки, полученный из запроса Создать поездку. Также необходимо включить параметры навигации, которые сообщают Google Картам или Waze о необходимости начать активную навигацию.

Google Карты

Для Google Карт укажите в URL запуска следующие параметры:

  • dir_action=navigate – этот параметр принудительно включает активную навигацию.
  • action_token – этот параметр предоставляет токен аутентифицированной поездки.

В примерах ниже показано, как форматировать URL запуска для 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
  • Идентификатор места:
    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)

Чтобы начать поездку с Navigation Connect, необходимо связать сеанс навигации с приложением на Android. Для этого укажите идентификатор подтвержденного приложения. Это позволяет идентифицировать ваше приложение как источник поездки, чтобы Google Карты или Waze могли связать активную поездку с вашей платформой. Если идентификатор приложения отсутствует или недействителен, аутентификация токена поездки не выполняется.

Если вы укажете идентификатор приложения, то сможете:

  • Авторизация передачи данных. Проверяет, разрешено ли вашему приложению получать данные об активных поездках.
  • Включить согласие водителя. В окне запроса доступа будут показаны название вашей компании и политика конфиденциальности, чтобы водитель знал, кто получает данные о его текущем местоположении и расчетном времени прибытия.
  • Включить кнопку возврата. Позволяет Google Картам или Waze создать брендированную кнопку возврата, чтобы водители могли переключиться обратно на ваше приложение.

Чтобы передать идентификатор приложения в Google Карты или Waze на устройстве Android, добавьте название пакета в намерение запуска (которое содержит строку URL запуска) с помощью Intent.EXTRA_REFERRER_NAME.

В примере ниже показано, как добавить название пакета в намерение.

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

Как разрешить водителям возвращаться в ваше приложение

Приложение "Google Карты" с нижней панелью, на которой слева расположены кнопка "Назад", название приложения и значок передачи данных. Приложение Waze с кнопкой "Назад" в фирменном стиле справа.

Navigation Connect показывает нижнюю панель (Google Карты) или брендированную кнопку "Назад" (Waze), чтобы водитель мог легко вернуться в ваше приложение в любой момент поездки или по прибытии в пункт назначения.

Android

Вам нужно создать PendingIntent, который будет указывать на действие в приложении. Прикрепите этот объект PendingIntent в качестве дополнительного к намерению запуска, используя точный ключ "pendingIntent". Когда пользователь нажимает кнопку возврата, Google Карты или Waze выполняют это намерение, чтобы вывести ваше приложение на передний план.

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

iOS (только Waze)

Чтобы включить кнопку возврата, не нужно ничего добавлять в URL запуска. Waze автоматически использует универсальную ссылку, которую вы зарегистрировали при подтверждении приложения.

Примеры кода

В примерах кода ниже показано, как запустить Google Карты или Waze из приложения с помощью Navigation Connect и включить кнопку "Вернуться в приложение".

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