Как передать динамические ярлыки в Ассистент

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

Например, вы можете создать ярлык для каждой заметки, которую пользователь создает в вашем приложении для заметок. Чтобы динамические ссылки могли показываться в сервисах Google, например в Ассистенте, добавьте в проект библиотеку Jetpack для интеграции ярлыков Google. Эта библиотека позволяет Ассистенту принимать динамические ярлыки, которые вы отправляете с помощью класса ShortcutManagerCompat, который является оболочкой Jetpack для API ShortcutManager.

Если вы используете в своем приложении библиотеку Google Shortcuts Integration, динамические ярлыки, которые вы отправляете в Google, будут видны пользователям в качестве подсказок для голосовых ярлыков в приложении "Ассистент". Вы можете отправить в Ассистент неограниченное количество динамических ярлыков с помощью метода pushDynamicShortcut() библиотеки ShortcutManagerCompat.

Как настроить проект разработки

Чтобы добавить в приложение динамические ярлыки, вам понадобится библиотека Google Shortcuts Integration, которая входит в Android Jetpack. В этом разделе описано, как настроить проект разработки приложения, чтобы включить эту библиотеку.

Чтобы добавить эту библиотеку Jetpack и настроить проект, выполните следующие действия:

  1. Обновите файл gradle.properties, чтобы он мог обрабатывать библиотеки Jetpack:

    gradle.properties

    android.useAndroidX=true
# Automatically convert third-party libraries to use AndroidX
android.enableJetifier=true

  2. Добавьте зависимости библиотеки Jetpack в файл build.gradle:

    app/build.gradle

    dependencies {
 implementation "androidx.core:core:1.6.0"
 implementation "androidx.core:core-google-shortcuts:1.0.1"
 ...
}

    В приведенном выше образце кода вы указываете две библиотеки Jetpack в качестве зависимостей. Библиотека androidx.core:core:1.6.0 содержит класс ShortcutManagerCompat, который используется для отправки динамических ярлыков в Google.

    androidx.core:core-google-shortcuts:1.0.1 – это библиотека интеграции ярлыков Google. В этой библиотеке нет API для разработчиков. Добавив ее в качестве зависимости, вы разрешите Ассистенту принимать динамические ярлыки, которые вы отправляете с помощью класса ShortcutManagerCompat.

Отправка динамических ярлыков

Чтобы передать динамические ярлыки, которые могут показываться в Ассистенте, сначала создайте ярлык с помощью класса ShortcutInfoCompat.Builder().

Затем вы отправляете ярлык с помощью метода ShortcutManagerCompat.pushDynamicShortcut(). Ярлыки отправляются, когда пользователь выполняет в приложении определенное действие. В примере кода ниже ярлык отправляется каждый раз, когда пользователь создает список в приложении для заметок и списков.

ExampleOrderActivity

Kotlin

// Define the dynamic shortcut for an item
var intent = Intent(context, DisplayOrderActivity::class.java)
intent.action = Intent.ACTION_VIEW
var shortcutInfo = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Running")
    .setLongLabel("Start running")
    .addCapabilityBinding(
        "actions.intent.CREATE_ITEM_LIST", "itemList.name", Arrays.asList("My First List")
    )
    .setIntent(intent) // Push the shortcut
    .build()

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo)

Java

// Define the dynamic shortcut for an item
Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat.Builder shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Running")
    .setLongLabel("Start running")
    .addCapabilityBinding(
      "actions.intent.CREATE_ITEM_LIST", "itemList.name", Arrays.asList("My First List"))
    .setIntent(intent)
    .build();

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

id, на который ссылается метод ShortcutInfoCompat.Builder в приведенном выше образце кода, определяет shortcutId результирующего объекта ярлыка. Значение id должно быть уникальным строковым литералом. Подробную информацию можно найти в документации по ярлыкам Android.

В предыдущем примере метод addCapabilityBinding связывает динамический ярлык с объектом capability того же типа android:name, который определен в shortcuts.xml. Этот метод позволяет связать ярлык с семантическим параметром встроенного намерения.

Динамические ярлыки иногда отправляются без какой-либо конкретной связи с параметром BII. Когда пользователь вызывает Ассистента, тот запускает intent, определенный в ярлыке, чтобы выполнить действие. В следующем примере показан динамический ярлык без связи с параметром:

Kotlin

var intent: Intent = Intent(context, DisplayOrderActivity::class.java)
intent.setPackage(this, "com.sample.app")
intent.setAction(Intent.ACTION_VIEW)

var shortcutInfo: ShortcutInfoCompat = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Create a list")
    .setLongLabel("Create a list")
    .addCapabilityBinding("actions.intent.CREATE_ITEM_LIST")
    .setIntent(intent)
    .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

Java

Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setPackage(this, "com.sample.app");
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
  .setShortLabel("Create a list")
  .setLongLabel("Create a list")
  .addCapabilityBinding("actions.intent.CREATE_ITEM_LIST")
  .setIntent(intent)
  .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

Как протестировать динамические ярлыки с помощью Ассистента

Когда Google Ассистент успешно принимает динамический ярлык из вашего приложения, этот ярлык может появиться в качестве рекомендуемого голосового ярлыка в приложении Ассистента для Android. В приложении Ассистента рекомендуются самые последние ярлыки, отправленные вашим приложением.

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

  1. Создайте предварительную версию действий в приложении и подготовьте тестовое устройство или эмулятор для проверки действий, следуя тем же требованиям к настройке, что и для плагина Google Ассистента.
  2. Откройте приложение и определите динамический ярлык, который нужно отправить. Затем выполните действие. Например, если вы создали ярлык, который срабатывает при создании заметки в приложении для заметок, создайте новую заметку.
  3. Откройте Быстрые команды в приложении Настройки Ассистента на устройстве. Динамический ярлык появится в списке для вашего приложения.