Как предлагать ярлыки с помощью In-App Promo SDK

Чтобы продвигать функции приложения и сделать его удобнее, вы можете предлагать пользователям быстрые команды Ассистента. Быстрые команды Ассистента – это короткие фразы, которые пользователь может произнести, чтобы запустить функцию в вашем приложении.

Пользователи могут создавать быстрые команды Ассистента вручную, но In-App Promo SDK позволяет предлагать и внедрять их. Предлагая ярлыки, вы даете пользователям понятные и простые способы вернуться к любимым действиям в приложении без необходимости настраивать ярлыки.

Например, если пользователь ищет в вашем музыкальном приложении "heavy metal workout", вы можете предложить ему быструю команду Ассистента, которая будет сразу открывать результаты этого поиска. Когда вы предлагаете быструю команду, в приложении появляется подсказка с предложенной фразой и вопросом, можно ли создать быструю команду.

В этом примере вы предлагаете фразу "Включи музыку для тренировки". Пользователь принимает предложение и теперь может запустить ярлык, сказав "Окей, Google, включи музыку для тренировки".

Подробнее о том, как расширить аудиторию приложения с помощью действий в приложении…

In-App Promo SDK предоставляет следующие методы:

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

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

  • createShortcutSettingsIntent: возвращает намерение, которое можно использовать, чтобы перенаправить пользователя в настройки быстрых команд Ассистента для вашего приложения.

Требования и ограничения

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

Предварительные требования к разработке

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

  • Добавьте в приложение для Android поддержку действий в приложениях.

  • Включите com.google.android.googlequicksearchbox в тег <queries> в манифесте. Пример:

    <manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

  • Публикуйте приложения в формате набора Android App Bundle.

Требования к устройствам

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

  • Последняя версия приложения Google.

  • Android 6.0 (уровень API 23) или более поздней версии;

Известные ограничения

Подсказки поддерживаются только на английском языке. Чтобы пользователи видели ваши подсказки, они должны установить английский язык для Ассистента на своем устройстве.

Применить предложения

Чтобы реализовать подсказки, вам нужно обновить файл build.gradle, настроить клиент подсказок, а затем определить подсказки, которые вы хотите показывать пользователям.

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

    dependencies {
  ...
  implementation "com.google.assistant.appactions:suggestions:1.0.0"
}

  2. Определите экземпляр AssistantShortcutSuggestionsClient.

    Kotlin

    val shortcutsClient =
  AssistantShortcutSuggestionsClient.builder()
    .setContext(CONTEXT: Context)
    .setVerifyIntents(VERIFY_INTENTS: Boolean)
    .setCustomExecutor(CUSTOM_EXECUTOR: Object)
    .build()

    Java

    AssistantShortcutSuggestionsClient shortcutsClient =
  AssistantShortcutSuggestionsClient.builder()
    .setContext(CONTEXT: Context)
    .setVerifyIntents(VERIFY_INTENTS: Boolean)
    .setCustomExecutor(CUSTOM_EXECUTOR: Object)
    .build();

    В этом примере:

    • CONTEXT (обязательный параметр) – контекст приложения.

    • VERIFY_INTENTS (обязательно) определяет, нужно ли проверять каждое намерение, созданное при предложении пользователям быстрых команд. Когда true, намерения, созданные AssistantShortcutSuggestionsClient, проверяются. Если намерение недействительно, возвращается исключение.

    • CUSTOM_EXECUTOR (необязательно) – специальный исполнитель для запуска асинхронных задач. Если он не указан, SDK использует однопоточный исполнитель.

  3. Используйте метод lookupShortcut, чтобы определить, является ли ярлык, который вы хотите предложить, действительным и, при необходимости, существует ли он уже.

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

      Kotlin

      val exercise = mapOf(
    "@type" to "Exercise",
    "@context" to "http://schema.googleapis.com",
    "name" to "Running",
)

val appShortcutIntent = AppShortcutIntent.builder()
    .setIntentName("actions.intent.START_EXERCISE")
    .setPackageName("my.app.package")
    .setIntentParamName("exercise")
    .setIntentParamValue(exercise)
    .build()

      Java

        Map<String, Object> exercise = new HashMap<>();
  exercise.put("@type", "Exercise");
  menuItem.put("@context", "http://schema.googleapis.com");
  menuItem.put("name", "Running");

  AppShortcutIntent appShortcutIntent =
      AppShortcutIntent.builder()
          .setIntentName("actions.intent.START_EXERCISE")
          .setPackageName("my.app.package")
          .setIntentParamName("exercise")
          .setIntentParamValue(exercise)
          .build();

    2. Передайте намерение ярлыка методу lookupShortcut.

      Kotlin

      val result = shortcutsClient.lookupShortcut(appShortcutIntent).await()
if (!result.isShortcutPresent) {
    // App can suggest creating a shortcut
} else {
    // App can remind the user that they have a shortcut for this app action
}

      Java

      shortcutsClient.lookupShortcut(appShortcutIntent)
  .addOnSuccessListener(shortcutLookupResult -> {
    if (!shortcutLookupResult.isShortcutPresent()) {
      // App can suggest creating a shortcut
    } else {
      // App can remind the user that they have a shortcut for this app action
    }
  })
  .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));

  4. Создайте подсказку, используя намерение ярлыка. Есть два способа создать предложение:

    • createShortcutSuggestionIntent возвращает намерение Android, которое вы используете для запуска действия по предложению ярлыка в контексте вашего приложения.

      Kotlin

      val exerciseShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand(PHRASE: String)
    .build()

val intent = shortcutsClient.createShortcutSuggestionIntent(exerciseShortcut).await()
application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))

      Java

        AppShortcutSuggestion exerciseShortcut =
      AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand(PHRASE: String)
          .build();

  shortcutsClient.createShortcutSuggestionIntent(exerciseShortcut)
      .addOnSuccessListener(intent ->
          getApplication().startActivity(
              intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
      )
      .addOnFailureListener(e ->
          Log.e(TAG, "Failed to get shortcut suggestion intent", e);
      );

      В этом примере PHRASE – это фраза, которую вы хотите предложить пользователю в качестве быстрого действия. Например, если вы хотите, чтобы пользователь мог сказать "Окей, Google, начни пробежку", замените PHRASE на "start a run".

      Kotlin

      val exerciseShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand("start a run")
    .build()

      Java

      AppShortcutSuggestion exerciseShortcut =
    AppShortcutSuggestion.builder()
        .setAppShortcutIntent(appShortcutIntent)
        .setCommand("start a run")
        .build();

    • createShortcutSettingsIntent: возвращает интент Android, который перенаправляет пользователя в интерфейс настроек быстрых команд в приложении "Помощник".

      Kotlin

      val intent = shortcutsClient.createShortcutSettingsIntent().await()
application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))

      Java

        shortcutsClient.createShortcutSettingsIntent()
    .addOnSuccessListener(intent ->
        getApplication().startActivity(
            intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
    )
    .addOnFailureListener(e ->
        Log.e(TAG, "Failed to get shortcut settings intent", e);
    );

  5. Вызовите startActivity, используя объект intent Android, полученный на предыдущем шаге.

Рекомендации по устранению неполадок

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

GoogleInstallationUnsupportedException: Cannot bind to service

Из-за фильтрации видимости пакетов в Android 11 и более поздних версиях может возникать ошибка "GoogleInstallationUnsupportedException: Cannot bind to service". Убедитесь, что элемент com.google.android.googlequicksearchbox включен в тег <queries> в манифесте:

<manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

"Не удалось проверить подпись APK-файла"

Если вы не отправите рабочую версию приложения в виде набора App Bundle, может возникнуть следующая ошибка:

Failed to verify the APK signature. If this is a development build, please
make sure to update the preview of your app in App Actions Test Tool.

Убедитесь, что вы отправили приложение в формате Android App Bundle.

"Не удалось получить ярлыки пользователя"

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

Чтобы синхронизировать данные о быстрых командах на устройстве, добавьте или удалите быструю команду Ассистента в интерфейсе приложения "Помощник".

Окно создания ярлыка сразу закрывается, и контент не показывается.

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