Sugerowanie skrótów za pomocą pakietu SDK do promocji w aplikacji

Aby promować funkcje aplikacji i ułatwić korzystanie z niej, możesz sugerować użytkownikom skróty Asystenta. Skróty Asystenta to krótkie wyrażenia, które użytkownik może wypowiedzieć, aby uruchomić funkcję w aplikacji.

Użytkownicy mogą tworzyć skróty Asystenta ręcznie, ale pakiet SDK In-App Promo umożliwia proaktywne sugerowanie i wdrażanie skrótów Asystenta. Sugerując skróty, dajesz użytkownikom jasne i proste sposoby na powrót do ulubionych działań w aplikacji bez konieczności konfigurowania skrótów.

Jeśli na przykład użytkownik wyszuka w aplikacji muzycznej „heavy metal do ćwiczeń”, możesz zasugerować skrót Asystenta bezpośrednio do tych wyników wyszukiwania w przyszłości. Gdy zasugerujesz skrót, w aplikacji pojawi się komunikat z proponowaną frazą skrótu i pytaniem, czy użytkownik chce utworzyć skrót.

W tym przykładzie sugerujesz wyrażenie „włącz moją playlistę z heavy metalem do ćwiczeń”. Użytkownik akceptuje sugestię i może uruchomić skrót, mówiąc: „OK Google, włącz heavy metal do ćwiczeń”.

Więcej informacji o sposobach na zwiększenie liczby odbiorców aplikacji znajdziesz w artykule Rozwijanie aplikacji dzięki akcjom w aplikacji.

Pakiet SDK In-App Promo udostępnia te metody:

  • lookupShortcut: sprawdza, czy skrót, który chcesz zasugerować, już istnieje. Metoda sprawdza też, czy nie występują problemy uniemożliwiające utworzenie skrótu. Jeśli nie można utworzyć skrótu, lookupShortcut zwraca przyczyny.

  • createShortcutSuggestionIntent: zwraca intencję, której możesz użyć, aby poprosić użytkownika o utworzenie sugerowanego skrótu.

  • createShortcutSettingsIntent: zwraca intencję, której możesz użyć, aby przenieść użytkownika do ustawień skrótu Asystenta w aplikacji.

Wymagania wstępne i ograniczenia

W tej sekcji opisano wymagania wstępne i wymagania dotyczące korzystania z sugestii, a także ograniczenia, które możesz napotkać.

Wymagania wstępne dotyczące programowania

Aby korzystać z sugestii, Twoje środowisko programistyczne musi spełniać te wymagania.

  • Rozszerz aplikację na Androida, aby korzystać z akcji w aplikacji.

  • Dodaj com.google.android.googlequicksearchbox w tagu <queries> w pliku manifestu. Na przykład:

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

  • Do publikowania aplikacji używaj pakietów Android App Bundle.

Wymagania dotyczące urządzeń

Aby przetestować sugestie na urządzeniu, musisz mieć na nim zainstalowane te aplikacje:

  • najnowsza wersja aplikacji Google,

  • Android 6.0 (poziom interfejsu API 23) lub nowszy,

Znane ograniczenia

Sugestie są obsługiwane tylko w języku angielskim. Aby użytkownicy mogli zobaczyć Twoje sugestie, muszą ustawić język Asystenta na urządzeniu na angielski.

Wdrażanie sugestii

Aby wdrożyć sugestie, musisz zaktualizować plik build.gradle, skonfigurować klienta sugestii, a następnie zdefiniować sugestie, które chcesz przekazywać użytkownikom.

  1. Dodaj zależność biblioteki do pliku build.gradle.

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

  2. Zdefiniuj instancję 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();

    W tym przykładzie:

    • CONTEXT (wymagany) to kontekst aplikacji.

    • VERIFY_INTENTS (wymagany) określa, czy należy weryfikować każdą intencję utworzoną podczas sugerowania skrótów użytkownikom. Gdy true, intencje utworzone przez AssistantShortcutSuggestionsClient są weryfikowane. Jeśli intencja jest nieprawidłowa, zwracany jest wyjątek.

    • CUSTOM_EXECUTOR (opcjonalny) to niestandardowy wykonawca do uruchamiania zadań asynchronicznych. Jeśli nie zostanie podany, pakiet SDK użyje do tego zadania wykonawcy jednowątkowego.

  3. Użyj metody lookupShortcut, aby określić, czy skrót, który chcesz zasugerować, jest prawidłowy i czy już istnieje.

    1. Utwórz intencję skrótu do aplikacji. Intencja skrótu reprezentuje skrót, który chcesz zasugerować użytkownikowi. Ten przykład tworzy intencję skrótu do rozpoczęcia ćwiczenia.

      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. Przekaż intencję skrótu do metody 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. Utwórz sugestię, używając intencji skrótu. Sugestię możesz utworzyć na 2 sposoby:

    • createShortcutSuggestionIntent: zwraca intencję Androida, której używasz do rozpoczęcia aktywności związanej z sugestią skrótu w kontekście aplikacji.

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

      W tym przykładzie PHRASE to wypowiedź, którą chcesz zasugerować użytkownikowi jako skrót. Jeśli na przykład chcesz, aby użytkownik powiedział „OK Google, zacznij bieg” jako skrót, zastąp PHRASE ciągiem "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: zwraca intencję Androida, która przenosi użytkownika do interfejsu ustawień skrótów w aplikacji asystującej.

      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. Wywołaj startActivity, używając intencji Androida zwróconej w poprzednim kroku.

Rozwiązywanie problemów z sugestiami

W tej sekcji znajdziesz listę problemów i wyjątków, które mogą wystąpić podczas sugerowania skrótów.

"GoogleInstallationUnsupportedException: Cannot bind to service"

Z powodu filtrowania widoczności pakietów na urządzeniach z Androidem 11 lub nowszym może wystąpić błąd „GoogleInstallationUnsupportedException: nie można powiązać z usługą”. Upewnij się, że w tagu <queries> w pliku manifestu znajduje się com.google.android.googlequicksearchbox:

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

„Nie udało się zweryfikować podpisu pliku APK”

Jeśli nie prześlesz aplikacji w wersji produkcyjnej jako pakietu aplikacji, może wystąpić ten błąd:

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.

Upewnij się, że przesyłasz aplikację jako pakiet Android App Bundle.

„Nie udało się pobrać skrótów użytkownika”

Komunikat o błędzie „Nie udało się pobrać skrótów użytkownika” może się pojawić, jeśli niedawno dodano konto do urządzenia, a dane skrótów nowego konta nie zostały jeszcze zapisane w pamięci podręcznej urządzenia.

Aby zsynchronizować dane skrótu na urządzeniu, dodaj lub usuń skrót Asystenta za pomocą interfejsu aplikacji Asystent.

Aktywność tworzenia skrótu natychmiast się zamyka bez wyświetlania żadnych treści

Jeśli nie utworzysz podglądu za pomocą narzędzia do testowania akcji w aplikacji lub jeśli podgląd wygaśnie, aktywność tworzenia skrótu może zostać zamknięta bez wyświetlania żadnych treści. Zaktualizuj podgląd i spróbuj ponownie.