Объекты Intent для Google Карт на платформе Android Automotive

С помощью намерений Android можно запустить навигацию в Google Картах для Android Automotive.

Обзор

На этой странице описаны намерения, которые можно использовать с Google Картами для Android Automotive. Подробную документацию для разработчиков Android можно найти по следующим ссылкам:

• Интенты и фильтры интентов
• Намерения, распространенные на платформе Android

Запросы намерений

Чтобы запустить Google Карты для Android Automotive с помощью намерения, сначала создайте объект Intent, указав его действие, URI и пакет.

• Действие. Все объекты intent в Google Картах вызываются как действие View (Просмотр): ACTION_VIEW.

• URI. В интентах Google Карт используются закодированные URI строки, которые указывают выбранное действие и данные, необходимые для его выполнения.

• Пакет. Вызов setPackage("com.google.android.apps.maps") гарантирует, что намерение будет обработано приложением "Google Карты" для Android. Если пакет не задан, система определяет, какие приложения могут обрабатывать намерение. Если доступно несколько приложений, вам может быть предложено выбрать одно из них.

После создания намерения вы можете запросить запуск связанного приложения несколькими способами. Обычно для этого используется метод startActivity(). Система запустит нужное приложение (в данном случае Google Карты) и начнет соответствующее действие Activity.

// Create a Uri from an intent string. Use the result to create an Intent.
Uri mapIntentUri =
Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
// Create an Intent from mapIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

Если система не сможет определить приложение, которое может ответить на намерение, ваше приложение может аварийно завершить работу. Поэтому, прежде чем показывать пользователю одно из этих намерений, убедитесь, что приложение-получатель установлено.

Чтобы проверить, может ли приложение получить намерение, вызовите метод resolveActivity() для объекта Intent. Если результат не равен null, значит есть хотя бы одно приложение, которое может обработать намерение, и можно безопасно вызвать startActivity(). Если результат равен null, не используйте намерение и по возможности отключите функцию, которая его вызывает.

if (mapIntent.resolveActivity(getPackageManager()) != null) {
...
}

Например, чтобы запустить пошаговую навигацию до зоопарка Таронга в Сиднее, можно использовать следующий код:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
startActivity(mapIntent);
}

Строки запросов с кодировкой URI

Все строки, передаваемые в намерения Google Карт, должны быть закодированы в формате URI. Например, строка "1st & Pike, Seattle" должна быть преобразована в 1st%20%26%20Pike%2C%20Seattle. Пробелы в строке кодируются символами %20 или заменяются знаком плюса (+).

Для кодирования строк можно использовать метод android.net.Uri encode(). Пример:

Uri mapIntentUri = Uri.parse("google.navigation:q=" + Uri.encode("1st & Pike, Seattle"));

Отображение карты

Используйте намерение geo:, чтобы показать карту с определенным местоположением и масштабом. Пример:

geo:latitude,longitude?z=zoom

Параметры

• latitude и longitude задают центральную точку карты.

• z – необязательный параметр, который задает начальный масштаб карты. Допустимые значения: от 0 (весь мир) до 21 (отдельные здания). Верхний предел может варьироваться в зависимости от данных карты, доступных для выбранного местоположения.

Пример

// Creates an intent that will load a map of San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Поиск места

Используйте это намерение, чтобы показывать поисковые запросы в пределах указанной области просмотра:

geo:latitude,longitude?q=query
geo:0,0?q=my+street+address

Параметры

Помимо параметров, используемых для показа карты, Поиск поддерживает следующий параметр:

• q определяет места, которые нужно выделить на карте. Параметр q обязателен для всех поисковых запросов. В качестве местоположения можно указать название места или адрес. Строка должна быть экранирована в URL, поэтому адрес "City Hall, New York, NY" должен быть преобразован в City+Hall%2CNew+York%2CNY.

Как использовать предпочтения для результатов поиска с координатами

Если вы ищете конкретное место, указывать широту и долготу необязательно, если они включены в параметр q. Однако если вы не знаете точный адрес или запрос неоднозначен, вы можете попытаться уточнить результаты поиска, указав координаты. Например, если вы ищете адрес "Ленина", то можете получить слишком много результатов:

// Searching for "101 Main Street" with no lat/long might return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Добавление широты и долготы в URI намерения позволяет получить результаты для определенной области:

// Searches for "101 Main Street" near San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Поиск на маршруте

Если во время навигации отправляется поисковое намерение geo:latitude,longitude?q=query, запускается поиск вдоль маршрута, а широта и долгота игнорируются.

Поиск стандартных категорий

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

Намерение категории имеет формат geo:lat,lng?c=category.

Используйте c=<pre-defined category> независимо от региональных настроек пользователя. Google Карты показывают релевантные результаты в подходящем регионе для этой категории. Пример:

// Search for gas stations nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?c=gas_station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Другие запросы по категориям

Если вы передадите общий поисковый запрос (например, "рестораны" или "кофейни") в местоположении пользователя, Google Карты для Android Automotive будут искать компании, соответствующие критериям. Если в намерении geo: указаны конкретные широта и долгота, поиск выполняется вокруг этого местоположения. Если местоположение не указано (например, geo:0,0), Google Карты попытаются найти компании поблизости. Пример:

// Search for restaurants nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Вы можете дополнительно уточнить результаты поиска, указав параметр масштабирования вместе со строкой запроса. В следующем примере при добавлении масштаба 10 поиск ресторанов выполняется на уровне города, а не поблизости:

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Запустить пошаговую навигацию

Документация по запуску пошаговой навигации на других устройствах Android доступна в статье Запуск пошаговой навигации в Google Maps Intents для Android.

Используйте это намерение, чтобы запустить навигацию в Google Картах с пошаговыми маршрутами до одного или нескольких адресов или координат. Маршруты всегда строятся от текущего местоположения пользователя.

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude
google.navigation:place=placename

Параметры

Чтобы запустить навигацию, используйте place или q с waypoints (необязательно). Чтобы отметить путевую точку как зарядную станцию, ознакомьтесь с разделом Как отправить план поездки на электромобиле в Google Карты.

• q задает конечную точку для навигационных запросов. Это могут быть координаты широты и долготы или адрес в формате запроса. Если строка запроса возвращает несколько результатов, будет выбран первый из них.

• place – задает конечную точку маршрута (дом или работа). Укажите home, чтобы проложить маршрут до дома пользователя, или work, чтобы проложить маршрут до его работы.

• avoid задает объекты, которых следует избегать при построении маршрута. avoid – необязательный параметр, который может принимать одно или несколько из следующих значений:

  • t за платные дороги
  • h для шоссе;
  • f для паромов

• waypoints – указывает одно или несколько промежуточных мест на маршруте до конечного пункта назначения, заданного параметром q. Вы можете указать несколько путевых точек, разделив их вертикальной чертой (|), например Berlin,Germany|Paris,France. Вы можете добавить столько путевых точек, сколько нужно. Путевые точки будут добавлены в маршрут в том же порядке, в котором они перечислены в URL. Каждая путевая точка может быть адресом или разделенными запятыми координатами широты и долготы. В одном намерении можно использовать и адреса, и координаты. Строки должны быть экранированы в URL, поэтому путевые точки, такие как "Berlin,Germany|Paris,France", должны быть преобразованы в Berlin%2CGermany%7CParis%2CFrance.

Примеры

Этот Intent запрашивает пошаговую навигацию до зоопарка Таронга в Сиднее (Австралия):

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Если вы не хотите платить за проезд или пользоваться паромом, вы можете запросить маршрут, который позволяет избежать этих ситуаций:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Если вы хотите проложить маршрут до дома, скажите:

Uri mapIntentUri = Uri.parse("google.navigation:place=home");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Чтобы запустить пошаговую навигацию по трем адресам в указанном порядке, передайте зоопарк Таронга в качестве конечного пункта назначения q, а офис Google в Сиднее и Сиднейский оперный театр – в качестве путевых точек:

1. Google Сидней

2. Сиднейский оперный театр

3. Зоопарк Таронга, Сидней, Австралия

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7CSydney+Opera+House");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Как и в случае с q, любую путевую точку можно задать не адресом, а координатами широты и долготы, разделенными запятой. Например, чтобы запустить навигацию, передав широту и долготу Сиднейского оперного театра вместо адреса, используйте следующий код:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7C-33.856159,151.215256");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Как отправить план поездки на электромобиле в Google Карты

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

Для остановок для подзарядки и целей поездки:

• Должен содержать название и координаты.
• Может содержать выходную мощность, которая используется для расчета времени зарядки.

Google использует название и координаты зарядной станции, чтобы найти соответствующее место и показать наглядные данные, такие как типы коннекторов, их общее количество, скорость зарядки, доступность в реальном времени, поддерживаемые способы оплаты и объекты инфраструктуры. Например, маршруты по открытым парковкам для финальной части навигации, часы работы, оценки. Чтобы зарядные станции соответствовали данным Google, используйте определенный <brand name>, например ChargePoint.

Параметры

Следующие параметры позволяют указать сведения о конечном пункте назначения и путевых точках, включая станции зарядки ЭМ.

Пункт назначения

Чтобы задать зарядную станцию в качестве конечного пункта назначения, используйте:

• q: широта и долгота зарядной станции.
• q_type: 1 указывает, что конечным пунктом назначения является зарядная станция.
• q_name – название конечного пункта назначения. Обязательно, если для атрибута q_type указано значение 1.
• q_power_output_kw: число с плавающей запятой, обозначающее выходную мощность зарядной станции в киловаттах. Необязателен.

Путевые точки

Для путевых точек все параметры представляют собой параллельные массивы значений, разделенные вертикальной чертой (|), в том же порядке, что и путевые точки, не включая конечный пункт назначения. Если количество элементов в параллельных массивах не совпадает, намерение считается некорректным.

Чтобы добавить одну или несколько путевых точек зарядных станций, используйте следующие необязательные параметры: Если один из пунктов назначения отмечен как зарядная станция, то для него обязательно нужно указать название путевой точки.

• waypoints – список путевых точек, как описано в намерении пошаговой навигации. Для путевых точек зарядных станций необходимо указать широту и долготу.

• waypoint_types – типы для каждой путевой точки, указанные в виде числа. 0 – любая остановка (значение по умолчанию), а 1 – зарядная станция.

• waypoint_names – названия путевых точек. Это поле обязательно для зарядных станций.

• waypoint_power_outputs_kw – числа с двойной точностью, обозначающие мощность зарядной станции в киловаттах. Для зарядных станций можно указать выходную мощность путевой точки, которая будет использоваться как резервная, если подходящая станция не найдена. Пустая ячейка означает, что значение не указано.

Поведение пользователей

Если в намерении поездки указано несколько пунктов назначения, на экране появится обзор маршрута, но навигация не запустится автоматически.

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

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

• Если совпадение найдено, Google Карты используют данные Google, чтобы показать зарядную станцию в пользовательском интерфейсе и предоставить рекомендацию по зарядке для этой станции.

• Если совпадение не найдено, для показа зарядной станции в интерфейсе и предоставления рекомендации по зарядке на ней используются данные, указанные в намерении (широта и долгота, название и выходная мощность).

Примеры

В примерах ниже показано, как создавать интенты для различных сценариев планирования поездок на электромобиле, включая навигацию по нескольким зарядным станциям и обработку неизвестных выходных мощностей.

Как проложить маршрут до пункта назначения через несколько зарядных станций

Следующий интент позволяет построить маршрут до конечного пункта назначения, Порт-Маккуори (Новый Южный Уэльс), с остановками на двух зарядных станциях: ChargePoint и Evie.

Пункты назначения по порядку:

1. Зарядная станция ChargePoint (местоположение: -32.9599188,151.6240806, выходная мощность: 6,6 кВт)

2. Станция зарядки Evie (местоположение: -31.9432539,152.4699808, выходная мощность: 350 кВт)

3. Порт-Маккуори, Новый Южный Уэльс

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806%7C-31.9432539%2C152.4699808"
            + "&waypoint_types=1%7C1"
            + "&waypoint_names=ChargePoint+Charging+Station%7CEvie+Charging+Station"
            + "&waypoint_power_outputs_kw=6.6%7C350");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Неизвестная выходная мощность

Если значение выходной мощности неизвестно, оставьте соответствующее поле waypoint_power_outputs_kw пустым. Если все слоты пусты, указывать параметр waypoint_power_outputs_kw не нужно.

Пункты назначения по порядку:

1. Зарядная станция ChargePoint (местоположение: -32.9599188,151.6240806, выходная мощность: неизвестно)

2. Порт-Маккуори, Новый Южный Уэльс

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806"
            + "&waypoint_types=1"
            + "&waypoint_names=ChargePoint+Charging+Station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Отметить конечный пункт как зарядную станцию

Чтобы отметить конечный пункт назначения как зарядную станцию, укажите параметры q_type, q_name и q_power_output_kw.

Пункты назначения по порядку:

1. Зоопарк Таронга, Сидней, Австралия

2. Зарядная станция ChargePoint (координаты: -32.9599188,151.6240806, выходная мощность: неизвестно)

3. Станция зарядки Evie (местоположение: -31.9432539,152.4699808, выходная мощность: 350 кВт)

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=-31.9432539,152.4699808&q_type=1&q_name=Evie+Charging+Station&q_power_output_kw=350"
            + "&waypoints=Taronga+Zoo%2C+Sydney+Australia%7C-32.9599188%2C151.6240806"
            + "&waypoint_types=0%7C1"
            + "&waypoint_names=%7CChargePoint+Charging+Station"
            + "&waypoint_power_outputs_kw=%7C");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Намерения действий

Доступны следующие намерения действий с интерфейсами: