Per promuovere le funzionalità della tua app e facilitarne l'utilizzo, puoi suggerire ai tuoi utenti le scorciatoie dell'assistente. Le scorciatoie dell'assistente sono frasi concise che un utente può pronunciare per attivare la funzionalità all'interno dell'app.
Sebbene le scorciatoie dell'assistente possano essere create manualmente dagli utenti, l'SDK In-App Promo ti consente di suggerire e implementare in modo proattivo le scorciatoie dell'assistente. Suggerendo le scorciatoie, fornisci agli utenti percorsi semplici e chiari per riportarli alle loro attività preferite nella tua app, senza dover configurare le scorciatoie.
Ad esempio, se un utente cerca "allenamento pesante" nella tua app di musica, in futuro potresti suggerire una scorciatoia dell'assistente direttamente a quei risultati di ricerca. Quando suggerisci una scorciatoia, nell'app viene visualizzato un messaggio che mostra la frase proposta per la scorciatoia e chiede all'utente se è possibile creare la scorciatoia.
In questo esempio, suggerisci la frase "inizia il mio allenamento heavy metal". L'utente accetta il suggerimento e può avviare la scorciatoia dicendo "Hey Google, avvia il mio esercizio di musica pesante".
Per ulteriori informazioni su come far crescere il pubblico della tua app, consulta Far crescere la tua app con le azioni app.
L'SDK per le promozioni in-app offre i seguenti metodi:
lookupShortcut
: controlla se la scorciatoia che vuoi suggerire esiste già. Il metodo verifica anche la presenza di eventuali problemi che impediscono la creazione della scorciatoia. Se non è possibile creare la scorciatoia,lookupShortcut
restituisce il motivo.createShortcutSuggestionIntent
: restituisce un intent che puoi utilizzare per chiedere all'utente di creare la scorciatoia suggerita.createShortcutSettingsIntent
: restituisce un intent che puoi utilizzare per spostare l'utente nelle impostazioni della scorciatoia dell'assistente per la tua app.
Prerequisiti e limitazioni
In questa sezione vengono descritti i prerequisiti e i requisiti per l'utilizzo dei suggerimenti, nonché le limitazioni che potresti riscontrare.
Prerequisiti di sviluppo
Per utilizzare i suggerimenti, il tuo ambiente di sviluppo deve soddisfare i seguenti prerequisiti.
Estendi la tua app per Android per utilizzare la funzionalità Azioni app.
Includi
com.google.android.googlequicksearchbox
all'interno del tag<queries>
nel tuo file manifest. Ecco alcuni esempi:<manifest ...> <queries> <package android:name="com.google.android.googlequicksearchbox" /> </queries> ... </manifest>
Utilizza gli Android App Bundle per pubblicare le tue app.
Requisiti del dispositivo
Per testare i tuoi suggerimenti su un dispositivo, è necessario che sul dispositivo sia installato quanto segue.
L'ultima versione dell'app Google
Android 6.0 (livello API 23) o versioni successive
Limitazioni note
I suggerimenti sono supportati solo in inglese. Per poter vedere i tuoi suggerimenti, gli utenti devono impostare l'inglese come lingua dell'assistente sul dispositivo.
Implementa suggerimenti
Per implementare i suggerimenti, devi aggiornare il file build.gradle
, impostare il client dei suggerimenti e poi definire i suggerimenti che vuoi fornire agli utenti.
Aggiungi la dipendenza dalla libreria al file
build.gradle
.dependencies { ... implementation "com.google.assistant.appactions:suggestions:1.0.0" }
Definisci un'istanza di
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();
In questo esempio:
CONTEXT
(obbligatorio) è il contesto dell'applicazione.VERIFY_INTENTS
(obbligatorio) determina se verificare ogni intent creato quando suggerisci scorciatoie agli utenti. Quandotrue
, vengono verificati gli intent creati daAssistantShortcutSuggestionsClient
. Se un intent non è valido, viene restituita un'eccezione.CUSTOM_EXECUTOR
(facoltativo) è un esecutore personalizzato per l'esecuzione di attività asincrone. Se non viene fornito, l'SDK utilizza un esecutore a thread singolo per l'attività.
Utilizza il metodo
lookupShortcut
per determinare se la scorciatoia da suggerire è valida e, facoltativamente, se esiste già.Crea un intent della scorciatoia app. L'intent della scorciatoia rappresenta la scorciatoia da suggerire a un utente. L'esempio seguente crea un intent per una scorciatoia per ordinare una bevanda.
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
menuItem = new HashMap<>(); menuItem.put("@type", "MenuItem"); menuItem.put("@context", "http://schema.googleapis.com"); menuItem.put("name", "Fresh Lemon Honey Jasmine Green Tea"); AppShortcutIntent appShortcutIntent = AppShortcutIntent.builder() .setIntentName("actions.intent.ORDER_MENU_ITEM") .setPackageName("my.app.package") .setIntentParamName("menuItem") .setIntentParamValue(menuItem) .build(); Passa l'intent della scorciatoia al metodo
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));
Crea il suggerimento utilizzando l'intent della scorciatoia. Esistono due metodi per creare un suggerimento:
createShortcutSuggestionIntent
: restituisce un intent Android che utilizzi per avviare l'attività di suggerimento di scorciatoie nel contesto della tua app.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); );
In questo esempio, PHRASE è l'espressione che vuoi suggerire all'utente come scorciatoia. Ad esempio, se vuoi che l'utente dica "Hey Google, ordina il mio bubble tea" come scorciatoia, sostituisci PHRASE con
"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
: restituisce un intent Android che sposta l'utente nell'interfaccia delle impostazioni della scorciatoia nell'app dell'assistente.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); );
Chiama
startActivity
utilizzando l'intent Android restituito durante il passaggio precedente.
Suggerimenti per la risoluzione dei problemi
In questa sezione vengono elencati i problemi e le eccezioni che potresti riscontrare quando suggerisci scorciatoie.
"GoogleInstallationSupportedException: Impossibile eseguire l'associazione al servizio"
A causa del filtro sulla visibilità dei pacchetti, su Android 11 e versioni successive potrebbe verificarsi il messaggio "GoogleInstallationUnsupportedException
: impossibile associarsi al servizio". Assicurati che com.google.android.googlequicksearchbox
sia incluso nel tag <queries>
del tuo file manifest:
<manifest ...>
<queries>
<package android:name="com.google.android.googlequicksearchbox" />
</queries>
...
</manifest>
"Impossibile verificare la firma dell'APK"
Se non invii la tua app di produzione come app bundle, può verificarsi il seguente errore:
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.
Assicurati di inviare l'app come Android App Bundle.
"Impossibile recuperare le scorciatoie utente"
Il messaggio di errore "Impossibile recuperare le scorciatoie utente" può essere visualizzato se di recente hai aggiunto un account al dispositivo e i dati delle scorciatoie del nuovo account non sono ancora memorizzati nella cache sul dispositivo.
Per sincronizzare i dati delle scorciatoie sul dispositivo, aggiungi o elimina una scorciatoia dell'assistente utilizzando l'interfaccia dell'app Assistente.
L'attività di creazione delle scorciatoie si chiude immediatamente senza mostrare contenuti
L'attività di creazione della scorciatoia può chiudersi senza visualizzare alcun contenuto se non crei un'anteprima utilizzando lo Strumento di test delle azioni app o se l'anteprima scade. Aggiorna l'anteprima e riprova.