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

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

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

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

В этом примере вы предлагаете фразу «начни тренировку в стиле хэви-метал». Пользователь принимает предложение и затем может запустить ярлык, сказав: «Эй, Google, начни мою тренировку по хэви-металу».

Дополнительную информацию о способах расширения аудитории вашего приложения см. в разделе Расширение приложения с помощью действий в приложении .

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

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

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

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

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

Предварительные условия и ограничения

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

Предпосылки развития

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

• Расширьте свое приложение Android, чтобы использовать действия приложения .

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

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

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

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

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

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

• Android 6.0 (уровень API 23) или выше

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

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

Реализуйте предложения

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

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

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

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

   Котлин

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

   Ява

   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. Создайте намерение ярлыка приложения. Назначение ярлыка представляет собой ярлык, который вы хотите предложить пользователю. В следующем примере создается намерение использовать ярлык для запуска упражнения.

      Котлин

      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()
       

      Ява

        Map 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 .

      Котлин

      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
      }
      

      Ява

      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, которое вы используете для запуска действия по предложению ярлыков в контексте вашего приложения.

     Котлин

     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))
     

     Ява

       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 в свое предложение.

     Котлин

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

     Ява

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

   • createShortcutSettingsIntent : возвращает намерение Android, которое перемещает пользователя к интерфейсу настроек ярлыка в приложении Assistant.

     Котлин

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

     Ява

       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 используя намерение Android, полученное на предыдущем шаге.

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

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

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

«GoogleInstallationUnsupportedException: невозможно привязаться к службе»

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

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

«Не удалось проверить подпись APK»

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

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 .

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

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

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

Действие по созданию ярлыка немедленно закрывается без отображения какого-либо содержимого.

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