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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Добавьте в приложение для 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".

     Примечание. Не включайте Hey Google в свое предложение.

     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.

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

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

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

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

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