Запустите Google Maps или Waze.

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

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

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

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

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

Сформируйте URL-адрес запуска.

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

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

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

Отформатируйте место назначения

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

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

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

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

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

Google Карты

Для запуска Google Maps добавьте в URL-адрес следующие параметры:

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

В следующих примерах показано, как отформатировать URL-адрес запуска Google Maps, используя различные форматы целевого адреса:

  • Координаты широты и долготы: 
    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).

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

Указание идентификатора вашего приложения активирует следующие функции:

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

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

В следующем примере показано, как добавить имя пакета в намерение:

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

Как вернуть водителей в ваше приложение

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

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

Android

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

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

iOS (только для Waze)

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

Примеры кода

Приведенные ниже примеры кода показывают, как запустить Google Maps или Waze из вашего приложения с помощью Navigation Connect и активировать кнопку «Вернуться в приложение».

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