![](https://developer.android.com/static/guide/app-actions/images/Fitness4-widget.png?authuser=8&hl=it)
GET_EXERCISE_OBSERVATION
.
Per molti intent, la risposta migliore è fornire all'utente una risposta semplice, una breve conferma o un'esperienza interattiva rapida. Puoi mostrare un widget dell'app Android nell'Assistente Google per soddisfare questo tipo di intent.
Questa guida spiega come soddisfare le query degli utenti all'assistente utilizzando i widget e come migliorare la tua esperienza con i widget per l'assistente con la libreria di estensioni widget di Azioni app.
Vantaggi
I widget sono visualizzazioni in miniatura delle applicazioni che possono essere incorporate sulle piattaforme Android, come Avvio app o la schermata di blocco. Con Azioni app, aumenti l'impatto dei tuoi widget rendendoli idonei per la visualizzazione nell'assistente:
- Rilevamento: mostra in modo proattivo i widget in risposta alle query in linguaggio naturale degli utenti.
- Coinvolgimento:mostra i widget in contesti in vivavoce, ad esempio quando l'assistente fornisce risultati personali nella schermata di blocco e su Android Auto.
- Conservazione: consente agli utenti di fissare i widget visualizzati nell'assistente in Avvio app. La funzionalità di blocco richiede la libreria delle estensioni widget.
In che modo l'assistente mostra i widget
Gli utenti possono richiamare i widget sull'assistente in due modi:
- Richiedere esplicitamente un widget per nome.
- Pronunciare una query all'assistente che attiva un intent integrato (BII) o un intent personalizzato configurato per il completamento dei widget.
Chiamata esplicita
Per richiamare esplicitamente i widget per qualsiasi app installata, gli utenti possono chiedere all'assistente cose come:
- "Hey Google, mostra il widget ExampleApp."
- "Widget di ExampleApp."
L'assistente mostra questi widget con un'introduzione generica: "AppEsempio dice: ecco un widget". Sebbene l'assistente restituisca in modo nativo i widget richiesti in questo modo senza alcun lavoro richiesto dallo sviluppatore dell'app, questo metodo di chiamata richiede all'utente di conoscere esplicitamente il widget per richiederlo. Per semplificare il rilevamento dei widget, utilizza il metodo di fulfillment dell'intent descritto nella sezione seguente.
Realizzazione dell'intent
Rendi i tuoi widget più facili da trovare usandoli per rispondere alle query in linguaggio naturale che gli utenti eseguono sull'assistente. Ad esempio, puoi restituire un widget ogni volta che un utente attiva il BII di GET_EXERCISE_OBSERVATION
nella tua app per il fitness chiedendo "Hey Google, quanti chilometri ho percorso questa settimana su AppEsempio?". Oltre a semplificare il rilevamento, l'integrazione dei widget con Azioni app offre i seguenti vantaggi:
- Accesso ai parametri: l'assistente fornisce i parametri intent estratti dalla query dell'utente al tuo widget, abilitando risposte personalizzate.
- Introduzioni di sintesi vocale personalizzate: puoi fornire una stringa di sintesi vocale (TTS) che l'assistente ti annunci quando mostra il widget.
- Blocco del widget:l'assistente visualizza un pulsante Aggiungi questo widget accanto al widget, per consentire agli utenti di bloccare facilmente i widget in Avvio app.
Implementare il fulfillment widget
Per implementare il fulfillment del widget per i tuoi intent, segui questi passaggi:
- Implementa un widget Android seguendo i passaggi descritti nella sezione Creare un widget semplice.
- Nel file di risorse
shortcuts.xml
dell'app, aggiungi un elemento<app-widget>
alla funzionalità contenente i dettagli di fulfillment e i tag BII<parameter>
. Aggiorna il widget per gestire i parametri. - Aggiungi la libreria delle estensioni widget richiesta, che consente all'assistente di trasmettere nomi e parametri BII ai tuoi widget. Inoltre, attiva introduzioni personalizzate di sintesi vocale e funzionalità di blocco dei widget.
La sezione seguente descrive lo schema <app-widget>
per shortcuts.xml
.
Schema widget
Gli elementi <app-widget>
sono definiti come fulfillment all'interno degli elementi
<capability>
in shortcuts.xml
. Richiedono i seguenti attributi, se non diversamente indicato come facoltativi:
Tag "scorciatoies.xml" | Contenuto in | Attributi |
---|---|---|
<app-widget> |
<capability> |
|
<parameter> |
<app-widget> |
|
<extra> |
<app-widget> |
|
Descrizione schema widget
<app-widget>
Elemento fulfillment widget di primo livello.
Attributi:
android:identifier
: l'identificatore per questo fulfillment. Questo valore deve essere univoco negli elementi di evasione<app-widget>
e<intent>
definiti all'interno di<capability>
.android:targetClass
: il nome completo della classeAppWidgetProvider
per gestire l'intent.
<parametro>
Mappa un parametro BII a un valore <parameter>
di intent. Puoi definire zero o più parametri per ogni elemento <app-widget>
. Durante il fulfillment, l'assistente passa i parametri aggiornando gli elementi aggiuntivi per l'istanza del widget sotto forma di coppie chiave-valore, con il seguente formato:
- Chiave: l'elemento
android:key
definito per il parametro. - Valore: il valore estratto da BII dall'input vocale dell'utente.
Per accedere a questi extra, puoi chiamare getAppWidgetOptions()
sull'oggetto AppWidgetManager
associato, che restituisce Bundle
contenente il nome dello strumento BII di attivazione e i relativi parametri. Per ulteriori dettagli, consulta Estrazione dei valori dei parametri.
Per ulteriori informazioni sulla corrispondenza dei parametri BII, consulta Dati dei parametri e corrispondenza.
<extra>
Tag facoltativo che dichiara che per questo widget viene utilizzata un'introduzione alla sintesi vocale personalizzata. Questo tag richiede i seguenti valori degli attributi:
android:name
:"hasTts"
android:value
:"true"
Codice di esempio
L'esempio seguente da un file shortcuts.xml
mostra una configurazione di fulfillment widget per una funzionalità BII di GET_EXERCISE_OBSERVATION
:
<capability android:name="actions.intent.GET_EXERCISE_OBSERVATION">
<app-widget
android:identifier="GET_EXERCISE_OBSERVATION_1"
android:targetClass="com.exampleapp.providers.exampleAppWidgetProvider"
android:targetPackage="com.exampleapp">
<parameter
android:name="exerciseObservation.aboutExercise.name"
android:key="exercisename">
</parameter>
<extra android:name="hasTts" android:value="true"/>
</app-widget>
</capability>
Puoi specificare più elementi <app-widget>
o utilizzare una combinazione di elementi <app-widget>
e <intent>
per funzionalità. Questo approccio ti consente di fornire un'esperienza personalizzata in base a diverse combinazioni di parametri forniti dagli utenti. Ad esempio, se l'utente non specifica un punto di partenza nella sua query, puoi indirizzarlo all'attività nella tua app che mostra le opzioni per impostare i punti di partenza e di arrivo. Consulta la sezione Intent di riserva per ulteriori informazioni sulla definizione degli intent di riserva.
Estrai i valori dei parametri
Nella seguente classe AppWidgetProvider
di esempio, la funzione privata
updateAppWidget()
viene utilizzata per estrarre il nome e i parametri BII dalle
opzioni widget Bundle
:
Kotlin
package com.example.exampleapp //... Other module imports import com.google.assistant.appactions.widgets.AppActionsWidgetExtension /** * Implementation of App Widget functionality. */ class MyAppWidget : AppWidgetProvider() { override fun onUpdate( context: Context, appWidgetManager: AppWidgetManager, appWidgetIds: IntArray ) { // There might be multiple widgets active, so update all of them for (appWidgetId in appWidgetIds) { updateAppWidget(context, appWidgetManager, appWidgetId) } } private fun updateAppWidget( context: Context, appWidgetManager: AppWidgetManager, appWidgetId: Int ) { val widgetText: CharSequence = context.getString(R.string.appwidget_text) // Construct the RemoteViews object val views = RemoteViews(context.packageName, R.layout.my_app_widget) views.setTextViewText(R.id.appwidget_text, widgetText) // Extract the name and parameters of the BII from the widget options val optionsBundle = appWidgetManager.getAppWidgetOptions(appWidgetId) val bii = optionsBundle.getString(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_BII) // "actions.intent.CREATE_TAXI_RESERVATION" val params = optionsBundle.getBundle(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_PARAMS) if (params != null && params.containsKey("dropoff")) { val dropoffLocation = params.getString("dropoff") // Build your RemoteViews with the extracted BII parameter // ... } appWidgetManager.updateAppWidget(appWidgetId, views) } }
Java
package com.example.exampleapp; //... Other module imports import com.google.assistant.appactions.widgets.AppActionsWidgetExtension; /** * Implementation of App Widget functionality. */ public class MyAppWidget extends AppWidgetProvider { @Override public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { // There might be multiple widgets active, so update all of them for (int appWidgetId : appWidgetIds) { updateAppWidget(context, appWidgetManager, appWidgetId); } } private static void updateAppWidget(Context context, AppWidgetManager appWidgetManager, int appWidgetId) { CharSequence widgetText = context.getString(R.string.appwidget_text); // Construct the RemoteViews object RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.my_app_widget); views.setTextViewText(R.id.appwidget_text, widgetText); // Extract the name and parameters of the BII from the widget options Bundle optionsBundle = appWidgetManager.getAppWidgetOptions(appWidgetId); String bii = optionsBundle.getString(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_BII); // "actions.intent.CREATE_TAXI_RESERVATION" Bundle params = optionsBundle.getBundle(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_PARAMS); if (params != null && params.containsKey(("dropoff"))){ String dropoffLocation = params.getString("dropoff"); // Build your RemoteViews with the extracted BII parameter // ... } appWidgetManager.updateAppWidget(appWidgetId, views); } }
Libreria dell'estensione Widgets
La libreria di estensioni widget per azioni app migliora i tuoi widget per offrirti l'assistente con l'assistente vocale. Questa libreria consente ai widget di ricevere importanti informazioni di fulfillment dallo BII di attivazione, tra cui il nome BII e gli eventuali parametri di intent estratti dalla query dell'utente.
Questa libreria Maven ti consente di fornire un'introduzione sulla sintesi vocale (TTS) personalizzata per ogni widget, consentendo all'assistente di annunciare un riepilogo dei contenuti visualizzati visivamente agli utenti. Consente inoltre il blocco in Avvio applicazioni, semplificando il salvataggio dei widget visualizzati nell'assistente nelle schermate di avvio.
Per iniziare, aggiungi la libreria alla sezione delle dipendenze del file build.gradle
per il modulo dell'app:
dependencies {
//...
implementation "com.google.assistant.appactions:widgets:0.0.1"
}
Introduzioni personalizzate
Dopo aver importato la libreria dell'estensione widget, puoi fornire introduzioni di sintesi vocale personalizzate per i tuoi widget. Per aggiungere la tua definizione all'elemento AppWidgetProvider
del widget, apri la classe nel tuo IDE e importa la libreria di Widgets Extension:
Kotlin
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension
Java
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;
Kotlin
package com.example.exampleapp //... Other module imports import com.google.assistant.appactions.widgets.AppActionsWidgetExtension /** * Implementation of App Widget functionality. */ object MyAppWidget : AppWidgetProvider() { fun updateAppWidget( context: Context?, appWidgetManager: AppWidgetManager, appWidgetId: Int ) { val appActionsWidgetExtension = AppActionsWidgetExtension.newBuilder(appWidgetManager) .setResponseSpeech("Hello world") // TTS to be played back to the user .setResponseText("Hello world!") // Response text to be displayed in Assistant .build() // Update widget with TTS appActionsWidgetExtension.updateWidget(appWidgetId) // Update widget UI appWidgetManager.updateAppWidget(appWidgetId, views) } }
Java
package com.example.exampleapp; //... Other module imports import com.google.assistant.appactions.widgets.AppActionsWidgetExtension; /** * Implementation of App Widget functionality. */ public class MyAppWidget extends AppWidgetProvider { static void updateAppWidget(Context context, AppWidgetManager appWidgetManager, int appWidgetId) { AppActionsWidgetExtension appActionsWidgetExtension = AppActionsWidgetExtension.newBuilder(appWidgetManager) .setResponseSpeech("Hello world") // TTS to be played back to the user .setResponseText("Hello world!") // Response text to be displayed in Assistant .build(); // Update widget with TTS appActionsWidgetExtension.updateWidget(appWidgetId); // Update widget UI appWidgetManager.updateAppWidget(appWidgetId, views); } }
Consigli sullo stile di sintesi vocale
Utilizza i seguenti suggerimenti di stile per ottimizzare le introduzioni dei widget personalizzati per la sintesi vocale e i prompt visualizzati.
Consiglio | consigliato | Sconsigliata |
---|---|---|
ContrazioniUtilizza le contrazioni nei prompt di sintesi vocale. I messaggi senza contrazioni suonano interrotti e robotici anziché naturali e conversazionali. Pronunciare parole come "non può" e "non fare" può sembrare punitivo e duro. |
ResponseSpeech (TTS)Mi dispiace, non riesco a trovare una prenotazione. ResponseText Mi dispiace, non riesco a trovare una prenotazione. |
ResponseSpeech (TTS)Mi dispiace, non riesco a trovare una prenotazione. ResponseText Mi dispiace, non riesco a trovare una prenotazione. |
VirgoleFai chiarezza usando le virgole seriali in elenchi di tre o più voci. Senza la virgola seriale, le singole voci dell'elenco potrebbero essere ascoltate in modo errato o interpretate come gruppi. Ad esempio, in "narcisi, margherite e girasoli", "margherite e girasoli" suonano come se fossero uniti. In "narcisi, margherite e girasoli", tutti e tre sono chiaramente separati. |
ResponseSpeech (TTS)I più apprezzati sono quelli di rose gialle, narcisi, margherite e girasoli. ResponseText I più apprezzati sono le rose gialle, i narcisi, le margherite e i girasoli. |
ResponseSpeech (TTS)I più apprezzati sono quelli di rose gialle, narcisi, margherite e girasoli. ResponseText I più apprezzati sono quelli di rose gialle, narcisi, margherite e girasoli. |
NumeriUtilizza i numeri invece del testo per rendere i contenuti visivi più visibili. |
ResponseSpeech (TTS)La tua pressione sanguigna è di 100 gradi maggiore di 80. ResponseText La tua pressione sanguigna è 100/80. |
ResponseSpeech (TTS)La tua pressione sanguigna è 100/80. ResponseText La tua pressione sanguigna è di centottanta più di ottanta. |
SimboliUtilizza simboli specializzati invece del testo per rendere i contenuti visivi più visibili. |
ResponseSpeech (TTS)Il tuo ultimo acquisto è stato di 24,65 $. ResponseText Il tuo ultimo acquisto è stato di 24,65 $. |
ResponseSpeech (TTS)Il tuo ultimo acquisto è stato di ventiquattro dollari e sessantacinque centesimi. ResponseText Il tuo ultimo acquisto è stato di ventiquattro dollari e sessantacinque centesimi. |
Evita gli stuzzichiniLe bellezze fanno sembrare le risposte lontane e formali. Abbandonali e mantieni la conversazione amichevole e informale. |
ResponseSpeech (TTS)Il tuo ordine è stato consegnato. ResponseText Il tuo ordine è stato consegnato. |
ResponseSpeech (TTS)Certo, posso aiutarti. Il tuo ordine è stato consegnato. ResponseText Certo, posso aiutarti. Il tuo ordine è stato consegnato. |
Evita i punti esclamativiPossono essere percepiti come grida. |
ResponseSpeech (TTS)Hai corso 2,4 miglia oggi. ResponseText Hai corso per 2,4 miglia oggi. |
ResponseSpeech (TTS)Hai corso per 2,4 km oggi! ResponseText Hai corso per 2,4 km oggi! |
TempoUsa i numeri: "5:15", invece di "cinque e quindici" o "un quarto dopo cinque". Per il formato a 12 ore, utilizza AM o PM. |
ResponseSpeech (TTS)La consegna dovrebbe arrivare entro le 08:15. ResponseText La consegna dovrebbe arrivare entro le 08:15. |
ResponseSpeech (TTS)La consegna dovrebbe arrivare entro 15 minuti e dopo le 8 del mattino di oggi. ResponseText La consegna dovrebbe arrivare entro le 8 del mattino di oggi entro 15 minuti. |
Non lanciarti in monologhiFornisci risposte informative, ma mantieni concise. Non entrare nei dettagli eccessivi senza un chiaro vantaggio per l'utente. |
ResponseSpeech (TTS)Il mese scorso hai utilizzato 159 ore di energia. ResponseText Il mese scorso hai utilizzato 159 ore di energia. |
ResponseSpeech (TTS)Il risparmio energetico è molto importante per il pianeta e l'ambiente. Il mese scorso hai utilizzato 159 ore di energia. Per questo mese hai utilizzato 58 ore di energia. ResponseText Il risparmio energetico è molto importante per il pianeta e l'ambiente. Il mese scorso hai utilizzato 159 ore di energia. Per questo mese hai utilizzato 58 ore di energia. |
Usa parole brevi e sempliciIl linguaggio semplice e semplice ha il richiamo più ampio, rendendolo accessibile a persone di ogni estrazione. |
ResponseSpeech (TTS)La tua ultima lettura di zuccheri nel sangue è stata 126. ResponseText La tua ultima lettura di zuccheri nel sangue è stata di 126 mg/dL. |
ResponseSpeech (TTS)Il penultimo livello di glicemia era 126. ResponseText Il penultimo livello di glicemia era 126. |
Blocco su Avvio app
La libreria di estensioni widget consente di visualizzare il pulsante Aggiungi questo widget insieme al widget nell'assistente. Per abilitare il blocco, aggiungi la seguente definizione del ricevitore a AndroidManifest.xml
:
<application>
<receiver android:name="com.google.assistant.appactions.widgets.pinappwidget.PinAppWidgetBroadcastReceiver"
android:exported="false">
<intent-filter>
<action android:name="com.google.assistant.appactions.widgets.COMPLETE_PIN_APP_WIDGET" />
</intent-filter>
</receiver>
<service
android:name=
"com.google.assistant.appactions.widgets.pinappwidget.PinAppWidgetService"
android:enabled="true"
android:exported="true">
<intent-filter>
<action
android:name="com.google.assistant.appactions.widgets.PIN_APP_WIDGET" />
</intent-filter>
</service>
</application>
Disponibilità inventario
Gli BII che supportano l'inventario in linea o l'inventario web possono estendere queste inventari ai fulfillment dei widget.
Inventario incorporato
Il seguente codice di un file shortcuts.xml
di esempio dimostra una funzionalità BII di START_EXERCISE
configurata per l'inventario in linea e l'evasione dei widget:
<capability
android:name="actions.intent.START_EXERCISE">
<app-widget
android:identifier="START_EXERCISE_1"
android:targetClass="com.example.exampleapp.StartExerciseAppWidgetProvider">
<parameter
android:name="exercise.name"
android:key="exerciseName"
app:shortcutMatchRequired="true">
</parameter>
</app-widget>
</capability>
<shortcut android:shortcutId="RunningShortcut">
<intent
android:action="android.intent.action.VIEW"
android:targetClass="com.example.exampleapp.StartExcerciseActivity" />
<capability-binding
android:capability="actions.intent.START_EXERCISE"
android:parameter="exercise.name"
android:value="running;runs" />
</shortcut>
Nell'esempio precedente, quando un utente attiva questa funzionalità chiedendo
all'assistente "Inizia a eseguire con ExampleApp", il pacchetto di opzioni per il fulfillment <app-widget>
contiene la seguente coppia chiave-valore:
- Chiave =
“exerciseName”
- Valore =
“RunningShortcut”
Inventario web
Il seguente codice da un file shortcuts.xml
di esempio mostra una funzionalità abilitata per l'inventario web e il completamento dei widget:
<shortcuts>
<capability
android:name="actions.intent.START_EXERCISE">
<app-widget
android:identifier="START_EXERCISE_1"
android:targetClass="com.example.exampleapp.CreateTaxiAppWidgetProvider">
<parameter
android:name="exercise.name"
android:key="exerciseName"
android:mimeType="text/*">
<data android:pathPattern="https://exampleapp.com/exercise/.*" />
</parameter>
</app-widget>
</capability>
</shortcuts>
Testa azioni app
Usa lo strumento di test delle azioni app, una funzionalità del plug-in dell'Assistente Google per Android Studio, per testare i widget su un dispositivo fisico o virtuale. Per utilizzare lo strumento di test, procedi nel seguente modo:
- Collega il dispositivo di test all'app in esecuzione.
- In Android Studio, vai a Strumenti > Azioni app > Strumento di test di Azioni app.
- Fai clic su Crea anteprima.
- Esegui l'app sul dispositivo di test con Android Studio.
- Usa l'app Assistente sul dispositivo di test per testare l'Azione app. Ad esempio, puoi dire ad esempio "Hey Google, quanti chilometri ho percorso questa settimana su ExampleApp?"
- Osserva il comportamento della tua app o utilizza il debugger di Android Studio per verificare il risultato dell'azione desiderato.
Norme sulla qualità
Questa sezione evidenzia i requisiti chiave e le best practice per l'integrazione di Azioni app con i widget.
Contenuti nei widget
- (Obbligatorio) Non mostrare annunci nei widget.
- I contenuti dei widget devono essere incentrati completamente sul raggiungimento dell'intento. Non provare a soddisfare più intent con un solo widget o aggiungere contenuti non pertinenti.
Gestire l'autenticazione
- (Obbligatorio) Se è necessaria l'autenticazione dell'utente per completare un flusso utente, restituisci un widget che spiega che l'utente deve continuare nell'app. L'autenticazione utente incorporata nell'Assistente Google non è supportata per Azioni app.
- Se gli utenti consentono alla tua app di mostrare i dati utilizzando i widget, puoi restituire un widget di errore in fase di runtime per gli utenti non autorizzati.
Intent di riserva
(Obbligatorio) In
shortcuts.xml
, fornisci sempre un valore<intent>
di riserva oltre al fulfillment del widget per una determinata funzionalità. Un intent di riserva è un elemento<intent>
senza valori<parameter>
obbligatori.Ciò consente all'assistente di completare un'azione quando la query dell'utente non contiene parametri richiesti dagli altri elementi di fulfillment definiti nella funzionalità. L'eccezione si verifica quando non ci sono parametri obbligatori per quella funzionalità, nel qual caso è necessario solo il fulfillment widget.
Utilizza l'intent di riserva per aprire l'app nella schermata pertinente, non nella schermata Home.
Il seguente codice di un file shortcuts.xml
di esempio dimostra un <capability>
con un <intent>
di riserva che supporta un fulfillment <app-widget>
principale:
<shortcuts>
<capability
android:name="actions.intent.CREATE_TAXI_RESERVATION">
<!-- Widget with required parameter, specified using the "android:required" attribute. -->
<app-widget
android:identifier="CREATE_TAXI_RESERVATION_1"
android:targetClass="com.example.myapplication.CreateTaxiAppWidgetProvider">
<parameter
android:name="taxiReservation.dropoffLocation.name"
android:key="dropoff"
android:required="true">
</parameter>
</app-widget>
<!-- Fallback intent with no parameters required to successfully execute. -->
<intent
android:identifier="CREATE_TAXI_RESERVATION_3"
android:action="myapplication.intent.CREATE_TAXI_RESERVATION_1"
android:targetClass="com.example.myapplication.TaxiReservationActivity">
</intent>
</capability>
</shortcuts>
Informativa sui dati di Google Play
Questa sezione elenca i dati degli utenti finali raccolti dalla versione più recente della libreria delle estensioni widget.
Questo SDK invia risposte di sintesi vocale (TTS) fornite dallo sviluppatore che vengono annunciate all'utente dall'Assistente Google utilizzando la tecnologia vocale dell'assistente. Queste informazioni non vengono memorizzate da Google.
Le azioni app potrebbero anche raccogliere metadati dell'app client per i seguenti scopi:
- Per monitorare i tassi di adozione di versioni dell'SDK diverse.
- Per quantificare l'utilizzo delle funzionalità dell'SDK nelle varie app.