Aby promować funkcje aplikacji i ułatwić sobie korzystanie z niej, możesz sugerować użytkownikom skróty Asystenta. Skróty Asystenta to zwięzłe wyrażenia, które użytkownik może wypowiedzieć, aby aktywować funkcje aplikacji.
Chociaż skróty Asystenta mogą być tworzone ręcznie przez użytkowników, pakiet SDK promocji w aplikacji umożliwia proaktywne sugerowanie i wdrażanie skrótów Asystenta. Sugerując skróty, dajesz użytkownikom jasne, proste ścieżki do ulubionych działań w aplikacji bez dodatkowej pracy związanej z konfigurowaniem skrótów.
Jeśli na przykład użytkownik wyszuka w Twojej aplikacji muzycznej „heavy metal trening”, możesz w przyszłości zasugerować skrót do Asystenta bezpośrednio do tych wyników wyszukiwania. Gdy zasugerujesz skrót, w aplikacji pojawi się prośba z propozycją skrótu i pytaniem, czy można utworzyć skrót.
W tym przykładzie sugerujesz wyrażenie „rozpocznij trening heavy metalu”. Użytkownik akceptuje sugestię i może uruchomić skrót, mówiąc „OK Google, rozpocznij mój trening hard metalowy”.
Więcej informacji o poszerzaniu grona odbiorców aplikacji znajdziesz w artykule Zwiększanie liczby działań w aplikacji dzięki działaniom w niej.
Pakiet SDK promocji w aplikacji udostępnia te metody:
lookupShortcut: sprawdza, czy istnieje już sugerowany skrót. Sprawdza też, czy nie występują problemy, które uniemożliwiają utworzenie skrótu. Jeśli nie można utworzyć skrótu,lookupShortcutzwraca powód.createShortcutSuggestionIntent: zwraca intencję, która pozwala poprosić użytkownika o utworzenie sugerowanego skrótu.createShortcutSettingsIntent: zwraca intencję, której możesz użyć, aby przenieść użytkownika do ustawień skrótów Asystenta w aplikacji.
Wymagania wstępne i ograniczenia
W tej sekcji opisano wstępne wymagania i wymagania dotyczące korzystania z sugestii, a także ograniczenia, z którymi możesz natrafić.
Wymagania wstępne dla programistów
Aby można było korzystać z sugestii, środowisko programistyczne musi spełniać poniższe wymagania wstępne.
Rozszerz swoją aplikację na Androida, aby móc korzystać z działań w aplikacji.
Umieść
com.google.android.googlequicksearchboxw 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 można było przetestować sugestie na urządzeniu, na urządzeniu muszą być zainstalowane te aplikacje.
najnowszą wersję 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 widzieli Twoje sugestie, muszą ustawić na urządzeniu język Asystenta 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 przekazać użytkownikom.
Dodaj zależność biblioteki do pliku
build.gradle.dependencies { ... implementation "com.google.assistant.appactions:suggestions:1.0.0" }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 zweryfikować każdą intencję utworzoną podczas sugerowania użytkownikom skrótów. Gdytrue, intencje utworzone przezAssistantShortcutSuggestionsClientsą weryfikowane. Jeśli intencja jest nieprawidłowa, zwracany jest wyjątek.CUSTOM_EXECUTOR(opcjonalny) to niestandardowy wykonawca wykonujący zadania asynchroniczne. Jeśli nie zostanie podany, pakiet SDK użyje do tego zadania wykonawcy jednowątkowego.
Metoda
lookupShortcutpozwala określić, czy skrót, który chcesz zasugerować, jest prawidłowy, oraz opcjonalnie, czy skrót już istnieje.Utwórz intencję skrótu do aplikacji. Intencja skrótu reprezentuje skrót, który chcesz zasugerować użytkownikowi. Poniższy przykład pokazuje intencję dla skrótu do zamawiania napoju.
Kotlin
val menuItem = mapOf( "@type" to "MenuItem", "@context" to "http://schema.googleapis.com", "name" to "Fresh Lemon Honey Jasmine Green Tea", ) val appShortcutIntent = AppShortcutIntent.builder() .setIntentName("actions.intent.ORDER_MENU_ITEM") .setPackageName("my.app.package") .setIntentParamName("menuItem") .setIntentParamValue(menuItem) .build()Java
Map
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));
Utwórz sugestię za pomocą intencji skrótu. Można utworzyć sugestię na 2 sposoby:
createShortcutSuggestionIntent: zwraca intencję Androida, której używasz do uruchamiania sugerowanego skrótu w kontekście swojej aplikacji.Kotlin
val orderShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand(PHRASE: String) .build() val intent = shortcutsClient.createShortcutSuggestionIntent(orderShortcut).await() application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))Java
AppShortcutSuggestion orderShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand(PHRASE: String) .build(); shortcutsClient.createShortcutSuggestionIntent(orderShortcut) .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 wyrażenie, które chcesz zasugerować użytkownikowi jako skrót. Jeśli na przykład chcesz, by użytkownik podawał skrót „OK Google, zamów moją herbatę bąbelkową”, zamień PHRASE na
"order my bubble tea".Kotlin
val orderShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand("order my bubble tea") .build()Java
AppShortcutSuggestion orderShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand("order my bubble tea") .build();createShortcutSettingsIntent: zwraca intencję Androida, która przenosi użytkownika do interfejsu ustawień skrótów w aplikacji Asystent.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); );
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, na które możesz natrafić podczas sugerowania skrótów.
„GoogleInstalacjaNieobsługiwana wyjątek: nie można powiązać z usługą”
Ze względu na filtrowanie widoczności pakietów komunikat „GoogleInstallationUnsupportedException: nie można powiązać z usługą” może się pojawić na Androidzie 11 i nowszych. Sprawdź, czy tag com.google.android.googlequicksearchbox jest uwzględniony w tagu <queries> w pliku manifestu:
<manifest ...>
<queries>
<package android:name="com.google.android.googlequicksearchbox" />
</queries>
...
</manifest>
„Nie udało się zweryfikować podpisu pakietu APK”
Jeśli nie prześlesz produkcyjnej wersji aplikacji 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.
Prześlij aplikację w formie pakietu 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 pojawić się, jeśli niedawno dodano konto do urządzenia, a dane skrótów do tego konta nie są jeszcze zapisane w pamięci podręcznej.
Aby zsynchronizować dane skrótów na urządzeniu, dodaj lub usuń skrót do Asystenta, korzystając z interfejsu aplikacji Asystent.
Aktywność związana z tworzeniem skrótów jest natychmiast zamykana bez wyświetlania żadnej treści
Jeśli nie utworzysz podglądu za pomocą narzędzia do testowania działań w aplikacji lub podgląd wygaśnie, możesz zakończyć proces tworzenia skrótu bez wyświetlania żadnej treści. Zaktualizuj podgląd i spróbuj ponownie.