Создать файл ярлыков.xml

После того как вы определите свою функциональность в приложении и соответствующее встроенное намерение (BII), которое необходимо реализовать, объявите BII, которые поддерживает ваша функциональность, определив элемент capability в файле ресурсов shortcuts.xml . Объявление BII как capability регистрирует поддержку этого семантического намерения в вашем приложении и позволяет выполнять голосовой запрос с помощью Google Assistant.

Ассистент использует обработку естественного языка для извлечения параметров из пользовательского запроса. Встроенная ссылка на намерения перечисляет поля, которые каждый BII может извлечь из связанного пользовательского запроса. Например, если пользователь вызывает возможность [ actions.intent.GET_FOOD_OBSERVATION ][] в вашем приложении, говоря: «Эй, Google, спроси в exampleApp, что я ел на обед в прошлую пятницу» , Ассистент извлекает следующие параметры BII из запроса пользователя. :

• foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
• foodObservation.startTime = "2024-09-06T00:00:00"
• foodObservation.endTime = "2024-09-06T23:59:59"

Помощник передает параметры BII в intent выполнения, определенное в capability . Один или несколько элементов intent могут быть определены с возможностью учитывать различные способы, которыми пользователь может вызвать BII. Например, вы можете определить intent выполнения, для которого требуются оба параметра BII в приведенном выше примере. Затем вы можете определить второе намерение, для которого требуется один параметр BII, foodObservation.forMeal , который сообщает обо всех приемах пищи в определенный день, например «Окей, Google, спроси в exampleApp, что я ел на обед».

Обзор

Вы настраиваете действия приложения с помощью файла shortcuts.xml размещенного в каталоге res/xml вашего проекта приложения, а затем создаете ссылку на shortcuts.xml в манифесте вашего приложения. Добавьте ссылку на shortcuts.xml в манифест приложения, выполнив следующие действия:

1. В файле манифеста вашего приложения ( AndroidManifest.xml ) найдите действие, фильтры намерений которого настроены на действие android.intent.action.MAIN и категорию android.intent.category.LAUNCHER .

2. Добавьте ссылку на shortcuts.xml в AndroidManifest.xml используя тег <meta-data> в Activity , который имеет фильтры намерений как для MAIN , так и для LAUNCHER , как показано ниже:

   <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
   

В приведенном выше примере объявляется ресурс XML для файла xml/shortcuts.xml в APK. Дополнительные сведения о настройке ярлыков см. в разделе Создание статических ярлыков в документации для разработчиков Android.

Библиотека Jetpack androidx.core:core:1.6.0 (или более поздняя версия) необходима в вашем проекте Android, чтобы избежать ошибок компиляции при определении возможностей действий приложения в shortcuts.xml . Подробности см. в разделе Начало работы с Android Jetpack .

Статические ярлыки

При определении capability вы можете объявить статические элементы shortcut в shortcuts.xml чтобы расширить функциональность возможности. Статические ярлыки обрабатываются Ассистентом, когда вы загружаете выпуск в консоль Google Play. Поскольку статические ярлыки можно создавать и обновлять только путем создания новых выпусков, они наиболее полезны для выделения общих действий и контента в вашем приложении.

Вы можете включить следующие функции действий приложения с помощью статических ярлыков:

• Ярлыки возможностей . Создайте ярлыки, которые запускают экземпляр вашей capability содержащий предопределенные значения параметров intent . Например, вы можете объявить ярлык приложения «Начать пробежку», который вызывает возможность START_EXERCISE BII в вашем фитнес-приложении.

  Эти ярлыки содержат атрибуты intent , shortLabel и longLabel , что позволяет предлагать и выполнять их в качестве фишек в упреждающих средах, таких как Ассистент, или при длительном нажатии значка приложения в средствах запуска Android. Ярлык действия также может служить ярлыком объекта, как описано ниже, путем его связывания с capability с помощью тега <capability-binding> .

• Ярлыки объектов . Ярлыки объектов предоставляют список поддерживаемых значений параметров для capability голосового запроса. Например, ярлык объекта со списком типов упражнений («поход», «бег» и т. д.), привязанный к BII-параметру exercise.name возможности START_EXERCISE . Если высказывание пользователя соответствует сущности, идентификатор shortcutId передается в намерение вместо необработанного значения пользовательского запроса.

  Entity не определяют атрибуты intent , shortLabel или longLabel и поэтому не предлагаются на упреждающих поверхностях. Подробную информацию см. в разделе Встроенная инвентаризация для действий приложения .

Схема возможностей

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

Описание схемы возможностей

В этом разделе описываются элементы схемы capability .

<возможность>

capability , определяющая намерение действия приложения, которое поддерживает ваше приложение. Каждый элемент <capability> в файле shortcuts.xml должен содержать хотя бы одно <intent> для обработки выполнения действия.

Атрибуты:

• android:name : встроенный идентификатор действия намерения (например, [ actions.intent.GET_FOOD_OBSERVATION ][]). Список поддерживаемых встроенных намерений см. в справочнике по встроенным намерениям .
• app:queryPatterns : ресурс строкового массива запросов, ожидаемых от пользователя для этого намерения. Этот атрибут применим только к пользовательским намерениям , поскольку BII уже включают модели распространенных способов, с помощью которых пользователи выражают задачи, которые они пытаются выполнить, или информацию, которую они ищут.

<намерение>

Элемент intent Android, определяющий, как пользовательский запрос должен выполняться с использованием функций приложения. Разработчики могут предоставлять несколько тегов <intent> в capability . Помощник пытается выполнить пользовательский запрос, используя первое <intent> в capability для которой предоставлены все необходимые параметры.

Атрибуты:

• android:action : тип Action намерения. По умолчанию ACTION_VIEW .
• android:targetClass : класс целевой активности, например: "com.example.exercise.ExerciseActivity"
• android:targetPackage : пакет, содержащий целевой класс Activity, например: "com.example.exercise
• android:data : это поле перезаписывается <url-template> , если этот тег объявлен в intent .

<url-шаблон>

Шаблон для создания URI глубокой ссылки , который будет открыт на устройстве. Шаблон можно расширить встроенными параметрами намерений, если доступны все необходимые параметры шаблона. Примеры шаблонов URL-адресов HTTP см. в статье Википедии о шаблонах URL-адресов . Формат шаблона соответствует спецификации шаблона URI RFC6570 .

Ниже приведены некоторые примеры значений шаблона URL-адреса:

Дополнительные сведения о настройке шаблонов URL-адресов см. в разделе «Шаблоны URL-адресов в выполнении» .

<дополнительно>

Определяет дополнительные данные для intent . Для действий приложения это поле используется только для включения [вызова приложения на переднем плане][] для capability .

<параметр>

Сопоставляет параметр BII со значениями параметров намерения. Для получения дополнительной информации см. Данные параметров и сопоставление .

Атрибуты:

• android:name : имя параметра BII, который будет связан с этим параметром intent . Имя должно быть полем конечного уровня параметра BII (например, foodObservation.aboutFood.name ).
• android:key : определяемый разработчиком ключ значения параметра BII. Например, вы можете определить contact_name для параметра message.recipient.name BII.
• android:mimeType : mimeType параметра, например text/* . Это поле необходимо только для параметров пользовательских намерений .
• android:required : объявляет, должен ли пользовательский запрос включать этот параметр, чтобы это намерение могло использоваться для выполнения. Если параметр недоступен, Ассистент пытается выполнить запрос пользователя, используя следующее intent определенное для capability .

<ярлык-выполнение>

Указывает, что intent определенное во встроенном ярлыке инвентаря для указанного параметра, будет использоваться для выполнения. Подробности см. в разделе «Выполнение с использованием ярлыков намерений» .

<параметр> (для <shortcut-fulfillment> >)

Необязательный атрибут, который сопоставляет один параметр BII с выполнением встроенных ярлыков инвентаризации. Подробности см. в разделе «Выполнение с использованием ярлыков намерений» .

Атрибут:

• android:name : имя параметра BII, который будет связан с выполнением ярлыков встроенного инвентаря. Имя должно быть полем конечного уровня параметра BII (например, menuItem.name ).

<кусок>

Позволяет Ассистенту внедрить результат запроса, соответствующего этой capability в виде фрагмента Android. Подробности см. в разделе «Интеграция действий приложения с фрагментами Android» .

Схема ярлыка

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

Описание схемы ярлыка

В этом разделе описаны элементы схемы shortcut .

<ярлык>

Android <shortcut> определенный в файле shortcuts.xml , с определенными атрибутами, которые относятся к действиям приложения. Строковые значения полей shortcutShortLabel и shortcutLongLabel доступны через строковые ресурсы APK.

Атрибуты:

• android:shortcutId : Идентификатор этого ярлыка.
• android:shortcutShortLabel : строковый ресурс, представляющий короткую сокращенную фразу. Например, "@string/callDavidShort" представляющий значение «Позвонить Дэвиду».
• android:shortcutLongLabel : строковый ресурс, представляющий длинную сокращенную фразу. Например, "@string/callDavidLong" представляющий значение «Сделать аудиовызов Дэвиду».

<намерение>

Намерение Android, связанное с этим ярлыком. Это intent выполняется, когда пользователь запускает этот ярлык с помощью голоса или касания.

Атрибуты намерения shortcut идентичны атрибутам intent capability .

<привязка возможностей>

Связывает shortcut с capability действий приложения. Добавление этого элемента в shortcut позволяет использовать его для голосового выполнения с помощью Assistant .

Атрибуты:

• android:key : атрибут android:name capability к которой привязан этот shortcut . Например, actions.intent.START_EXERCISE .

<привязка параметра>

Необязательный атрибут, который связывает shortcut с одним параметром capability App Actions. Если для shortcut определена parameter-binding , ярлык можно использовать для предоставления встроенного объекта инвентаризации для параметра BII. Дополнительные сведения см. в разделе Встроенная инвентаризация для действий приложения .

Атрибуты:

• android:key : имя параметра BII capability , с которым можно связать этот ярлык. Например, exercise.name .
• android:value : значение entity . Это может быть отдельная entity или список ресурсов.

<дополнительно>

extra данные пакета для ярлыка. SameAs — единственные данные, относящиеся к элементам shortcut действий приложения. URL-адрес SameAs относится к ссылочной веб-странице, которая однозначно идентифицирует объект. Используется для указания значения перечисления тогда и только тогда, когда тип параметра намерения является подтипом Schema.org/Enumeration . Это необходимо для полей параметров, типы которых являются подтипами schema.org/Enumeration (например: MealTypeBreakfast ).

Атрибуты:

• android:key : поддерживаемое значение для действий приложения: sameAs
• android:value : sameAs значение URL, что и URL.

Дополнительные сведения см. в разделе Сопоставление значений перечисляемых параметров .

Варианты реализации намерения

Вы определяете элементы intent в <capability> , чтобы объявить, как Assistant реагирует или выполняет голосовые команды пользователя, соответствующие этой возможности. Существует несколько способов настройки того, как intent запускает пункт назначения в вашем приложении, в зависимости от того, как структурирована навигация в вашем приложении.

Возможны следующие варианты выполнения:

• Явные намерения . Запустите определенный компонент приложения, определив атрибуты targetClass и targetPackage для intent . Это рекомендуемый метод выполнения действий приложения.

• Глубокие ссылки . Запускайте целевые приложения с помощью глубоких ссылок Android, определив тег <url-template> в элементе intent . Этот метод полезен, если навигация вашего приложения уже основана на глубоких ссылках.

• Данные намерения : вы можете указать URI выполнения в атрибуте intent android:data . Это поле перезаписывается данными <url-template> , если этот тег также определен в intent .

Данные параметров и сопоставление

По умолчанию Ассистент отправляет параметры BII, извлеченные из пользовательского запроса, в ваше приложение в качестве extra данных о intent Android, определенном в этой capability .

Альтернативно вы можете объявить тег <url-template> в capability , который содержит заполнители для динамических параметров. Этот шаблон сопоставляется с одним из ваших действий в Android с помощью URL-адреса ссылки на приложение , пользовательской схемы или URL-адреса на основе намерения .

Использование дополнительных возможностей намерения

Следующий пример демонстрирует явное намерение, определенное для реализации capability :

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Учитывая приведенный выше пример, для пользовательского запроса типа «Эй, Google, начни пробежку» приложение получает intent , которое вызывает компонент: targetPackage , targetClass . Компонент получает Extra с key = "exercise" , value = "Running" .

Использование шаблона URL-адреса для глубоких ссылок Android

Если ваше приложение уже может обрабатывать URL-адреса, связанные с приложением, с динамическими параметрами, вы можете определить <url-template> в intent генерировать глубокие ссылки Android для выполнения. В следующем примере определяется <url-template> :

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Учитывая приведенный выше пример, для запроса пользователя типа «Эй, Google, начни пробежку» приложение получает сгенерированный URL-адрес: «myapp://start?exercision=Running».

Чтобы сопоставить параметр BII с позицией в вашем URL-адресе, вы используете атрибут android:name тега <parameter> . Этот атрибут соответствует значению android:key в шаблоне URL-адреса, который вы хотите заменить информацией от пользователя. Значение android:key должно присутствовать в вашем <url-template> и быть заключено в фигурные скобки ( {} ).

Соответствие перечисляемым значениям параметров

Некоторые параметры BII предоставляют перечислимые значения для вашего намерения выполнения, например поддерживаемые текстовые значения RECORD_FOOD_OBSERVATION BII. Для этих параметров Ассистент сопоставляет запрос пользователя («Завтрак») с сущностью, значение sameAs которой соответствует URL-адресу схемы перечисления ( https://schema.googleapis.com/MealTypeBreakfast ). Чтобы связать значения перечисления с поддерживаемым entity , вы объявляете ассоциацию sameAs в своем shortcut . В следующем примере демонстрируется ассоциация sameAs для ярлыка встроенного объекта:

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

В приведенном выше примере, если возможность RECORD_FOOD_OBSERVATION инициирует сопоставление типа еды «завтрак», с intent выполнения отправляется следующее дополнительное сообщение:

• key = "for_meal"
• value = "meal_breakfast"

Функции

Следующие функции действий приложения доступны в файле shortcuts.xml .

Встроенный инвентарь для действий в приложении

Для некоторых параметров BII можно использовать ярлыки для направления извлечения объектов к набору поддерживаемых объектов, указанных в файле shortcuts.xml , который называется встроенной инвентаризацией. Подробную информацию см. в разделе Встроенная инвентаризация .

Пользовательские намерения

Пользовательские намерения можно объявить в файле shortcuts.xml для голосового включения функций вашего приложения, которые не соответствуют доступным BII. Хотя пользовательские намерения по своей функциональности аналогичны определению BII, для них требуются два дополнительных атрибута в файле shortcuts.xml :

• app:queryPatterns : ресурс массива, который объявляет различные шаблоны запросов для специального намерения.

• android:mimeType : тип параметра пользовательского намерения. Это поле не требуется для BII, где тип параметра известен. Для пользовательских параметров намерения необходимо объявить поддерживаемый семантический тип .

Дополнительные сведения см. в разделе Пользовательские намерения .