![](https://developer.android.com/static/guide/app-actions/images/Fitness4-widget.png?authuser=0000&hl=it)
GET_EXERCISE_OBSERVATION
.
Per molti intent, la risposta migliore è fornire una risposta semplice, breve conferma o un'esperienza interattiva rapida per l'utente. Puoi visualizzare un Widget per app per Android nell'Assistente Google per soddisfare questo tipo di intent.
Questa guida spiega come rispondere alle query degli utenti dell'assistente utilizzando i widget e come: Migliora la tua esperienza con i widget per l'assistente con Azioni app Libreria dell'estensione Widgets.
Vantaggi
I widget sono viste in miniatura delle applicazioni che possono essere incorporate in Android come Avvio app o la schermata di blocco. Con Azioni app, aumenti l'impatto dei widget rendendoli idonei per essere visualizzati nell'assistente:
- Rilevamento: visualizza in modo proattivo i widget in risposta alle richieste degli utenti. query in linguaggio naturale.
- Coinvolgimento: mostra widget in contesti in vivavoce, ad esempio quando L'assistente fornisce risultati personali nella schermata di blocco e su Android Auto.
- Fidelizzazione:consenti agli utenti di fissare i widget visualizzati in Assistente Google all'Avvio app. La funzionalità di blocco richiede Libreria dell'estensione Widgets.
Come l'assistente visualizza i widget
Gli utenti possono richiamare widget sull'assistente in due modi:
- Richiesta esplicita di un widget per nome.
- Pronunciare all'assistente una query che attiva una intent integrato (BII) o intent personalizzato configurato per completamento del widget.
Chiamata esplicita
Per richiamare esplicitamente i widget per qualsiasi app installata, gli utenti possono chiedere all'assistente ad esempio:
- "Hey Google, fammi vedere il widget EsempioApp."
- "Widget di ExampleApp."
L'assistente mostra questi widget con l'introduzione generica: "AppEsempio dice: "Ecco un widget". Mentre l'assistente restituisce in modo nativo i widget richiesti in in questo modo senza alcun intervento richiesto dallo sviluppatore dell'app, questo metodo di chiamata richiede all'utente di conoscere esplicitamente il widget per richiederlo. A per semplificare il rilevamento del widget, usa il metodo di completamento dell'intent descritto nel sezione successiva.
Fulfillment intent
Semplifica la ricerca dei tuoi widget utilizzandoli per rispettare la naturale
delle query relative alla lingua che gli utenti eseguono sull'assistente. Ad esempio, puoi restituire un
ogni volta che un utente attiva l'intent integrato GET_EXERCISE_OBSERVATION
nel tuo
app per l'attività fisica chiedendo "Hey Google, da quanti chilometri ho corso questa settimana
App di esempio?" Oltre a semplificare il rilevamento, l'integrazione di widget
Azioni app offre i seguenti vantaggi:
- Accesso ai parametri:l'assistente fornisce i parametri di intent estratti. dalla query dell'utente al widget, abilitando risposte personalizzate.
- Introduzioni della sintesi vocale personalizzata: puoi fornire una stringa di sintesi vocale (TTS) per consentire all'assistente di annunciare quando viene visualizzato il widget.
- Blocco del widget:l'assistente visualizza il pulsante Aggiungi questo widget vicino a il tuo widget, consentendo agli utenti di bloccare facilmente i widget su Avvio app.
Implementa il completamento del widget
Per implementare il completamento del widget per i tuoi intent:
- Implementa un widget Android seguendo i passaggi descritti in Crea un widget semplice.
- Nel file di risorse
shortcuts.xml
dell'app, aggiungi un elemento<app-widget>
alla funzionalità contenente dettagli di completamento e tag degli intent integrati<parameter>
. Aggiorna il tuo widget per gestire i parametri. - Aggiungi la libreria dell'estensione Widgets obbligatoria, che consente L'assistente passa i nomi e i parametri degli intent integrati ai tuoi widget. Inoltre, consente introduzione alla sintesi vocale personalizzata e blocco dei widget funzionalità.
La seguente sezione descrive lo schema <app-widget>
per shortcuts.xml
.
Schema widget
Gli elementi <app-widget>
sono definiti come completamenti all'interno di
<capability>
in shortcuts.xml
. Richiedono quanto segue.
, a meno che non siano indicati come facoltativi:
Tag "Shortcuts.xml" | All'interno di | Attributi |
---|---|---|
<app-widget> |
<capability> |
|
<parameter> |
<app-widget> |
|
<extra> |
<app-widget> |
|
Descrizione schema widget
<widget-app>
Elemento di completamento del widget di primo livello.
Attributi:
android:identifier
: l'identificatore di questo fulfillment. Questo valore deve Deve essere univoco per l'evasione degli ordini<app-widget>
e<intent>
definiti all'interno di un elemento<capability>
.android:targetClass
: il nome completo del corsoAppWidgetProvider
per gestire l'intento.
<parametro>
Mappa un parametro dell'intent integrato a un valore <parameter>
di intent. Puoi definire zero o
più parametri per ogni elemento <app-widget>
. Durante l'evasione dell'ordine, l'assistente
passa i parametri aggiornando gli extra per l'istanza del widget come coppie chiave-valore,
con il seguente formato:
- Chiave: il valore
android:key
definito per il parametro. - Valore: il valore che l'intent integrato estrae dall'input vocale di un utente.
Puoi accedere a questi extra chiamando il numero getAppWidgetOptions()
sul
AppWidgetManager
oggetto, che restituisce un oggetto Bundle
contenente il nome di
l'intent integrato di trigger e i suoi parametri. Consulta
Estrai i valori dei parametri per maggiori dettagli.
Per saperne di più sulla corrispondenza dei parametri degli intent integrati, consulta Dati dei parametri e corrispondenza.
<extra>
Tag facoltativo che dichiara l'utilizzo di un'introduzione alla sintesi vocale personalizzata questo widget. 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
dimostra un widget
configurazione di fulfillment per
GET_EXERCISE_OBSERVATION
Funzionalità degli intent integrati:
<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
<app-widget>
e <intent>
elementi per funzionalità. Questo approccio ti consente
offrono un'esperienza personalizzata in base a diverse combinazioni di parametri
forniti dagli utenti. Ad esempio, se l'utente non specifica un punto di consegna
nella sua query, puoi indirizzarlo all'attività nella tua app che mostra
opzioni per impostare gli indirizzi di partenza e arrivo. Consulta le
Sezione Intent di riserva per ulteriori informazioni
sulla definizione degli intent di fallback.
Estrarre i valori dei parametri
Nella seguente classe AppWidgetProvider
di esempio, la funzione privata
updateAppWidget()
viene utilizzato per estrarre il nome e i parametri dell'intent integrato
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 raccolta dell'estensione Widget Azioni app migliora i widget per con l'assistente vocale. Questa raccolta consente ai tuoi widget di ricevere importanti informazioni di completamento dall'intent integrato di trigger, tra cui ed eventuali parametri di intent estratti dalla query dell'utente.
Questa libreria Maven ti consente di fornire un'introduzione alla sintesi vocale (TTS) personalizzata per ogni widget, consentendo all'assistente di annunciare un riepilogo dei contenuti mostrati agli utenti visivamente. Consente inoltre di bloccare in Avvio app, rendendo consente agli utenti di salvare facilmente i widget visualizzati nell'assistente in Avvio app schermate.
Per iniziare, aggiungi la libreria alla sezione delle dipendenze del
build.gradle
file per il modulo dell'app:
dependencies {
//...
implementation "com.google.assistant.appactions:widgets:0.0.1"
}
Introduzioni personalizzate
Dopo aver importato la libreria dell'estensione Widgets, puoi fornire una sintesi vocale personalizzata
introduzioni per i widget. Per aggiungere la tua definizione al riquadro
AppWidgetProvider
, apri la classe nel tuo IDE e importa l'estensione Widgets
libreria:
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 di stile per la sintesi vocale
Utilizza i seguenti suggerimenti di stile per ottimizzare il widget personalizzato introduzioni per la sintesi vocale e i prompt visualizzati.
Consiglio | consigliato | Sconsigliato |
---|---|---|
ContrazioniUsa le contrazioni nei prompt di sintesi vocale. Messaggi senza suono di contrazioni forti e robotici piuttosto che naturali e conversazionali. Parole pronunciate come "non è possibile" e "da non fare" può sembrare punitivo e duro. |
ResponseSpeech (TTS)Mi dispiace, non riesco a trovare prenotazioni. ResponseText Mi dispiace, non riesco a trovare prenotazioni. |
ResponseSpeech (TTS)Mi dispiace, non riesco a trovare una prenotazione. ResponseText Mi dispiace, non riesco a trovare una prenotazione. |
VirgoleAggiungi chiarezza utilizzando virgole seriali in elenchi di tre o più elementi. Senza la virgola di serie, i singoli elementi dell'elenco potrebbero essere non viene rilevato in modo corretto o viene letto come gruppi. Ad esempio, in "narcisi, margherite e girasoli", "margherite e girasoli" sono come se si unissero. In "narcisi, margherite e girasoli", sono tutti e tre chiaramente separati. |
ResponseSpeech (TTS)I nostri più popolari includono rose gialle, narcisi, margherite e girasoli. ResponseText I nostri più popolari includono rose gialle, narcisi, margherite e girasoli. |
ResponseSpeech (TTS)I più popolari includono rose gialle, narcisi, margherite e girasoli. ResponseText I più popolari includono rose gialle, narcisi, margherite e girasoli. |
NumeriUsa i numeri al posto del testo per rendere i contenuti visivi più visibili. |
ResponseSpeech (TTS)La tua pressione sanguigna è 100 su 80. ResponseText La tua pressione sanguigna è 100/80. |
ResponseSpeech (TTS)La tua pressione sanguigna è 100/80. ResponseText La tua pressione sanguigna è di centottanta gradi. |
SimboliUsa simboli specializzati al posto del testo per arricchire ulteriormente i contenuti visivi a colpo d'occhio. |
ResponseSpeech (TTS)L'ultimo acquisto è stato di 24,65 $. ResponseText L'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 le chiccheLe bellezze rendono le risposte distanti e formali. Dimenticali e mantieni amichevole e informale per le conversazioni. |
ResponseSpeech (TTS)Il tuo ordine è stato consegnato. ResponseText Il tuo ordine è stato consegnato. |
ResponseSpeech (TTS)Certo, te lo dico io. Il tuo ordine è stato consegnato. ResponseText Certo, te lo dico io. Il tuo ordine è stato consegnato. |
Evita punti esclamativiPossono essere percepiti come un grido. |
ResponseSpeech (TTS)Hai corso 2,5 km oggi. ResponseText Hai corso 2,5 km oggi. |
ResponseSpeech (TTS)Hai corso 2,5 km oggi! ResponseText Hai corso 2,5 km oggi! |
TempoUsa i numeri: "5:15", anziché "cinque- quindici" o "trimestre 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 dopo le 8 di oggi. ResponseText La consegna dovrebbe arrivare entro 15 minuti dopo le 8 di oggi. |
Non lanciare monologhiFornisci informazioni, ma mantieni risposte concise. Non andare troppo duro senza un chiaro vantaggio per l'utente. |
ResponseSpeech (TTS)Il mese scorso hai consumato 159 ore di energia. ResponseText Il mese scorso hai consumato 159 ore di energia. |
ResponseSpeech (TTS)Il risparmio energetico è molto importante per il pianeta e l'ambiente. Il mese scorso hai consumato 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 consumato 159 ore di energia. Per questo mese hai utilizzato 58 ore di energia. |
Usa parole brevi e sempliciUn linguaggio semplice e lineare ha il richiamo più ampio, rendendolo accessibile alle persone di ogni provenienza. |
ResponseSpeech (TTS)La tua ultima lettura di zuccheri nel sangue è stata 126. ResponseText La tua ultima lettura di zuccheri nel sangue è stata 126 mg/dL. |
ResponseSpeech (TTS)Il penultimo livello di glicemia era 126. ResponseText Il penultimo livello di glicemia era 126. |
Blocco in Avvio app
La libreria dell'estensione Widgets consente di visualizzare il pulsante Aggiungi questo widget
con il widget nell'assistente. Per attivare il blocco, aggiungi il seguente destinatario
definizione in 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 intent integrati che supportano l'inventario in linea o l'inventario web possono estendere gli inventari ai completamenti widget.
Inventario in linea
Il seguente codice di un file shortcuts.xml
di esempio dimostra una
START_EXERCISE
Funzionalità degli intent integrati
configurato per l'inventario in linea e l'evasione degli ordini 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
l'assistente, "Start running with ExampleApp", il pacchetto di opzioni per
Il completamento <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à
abilitato per l'inventario web e l'evasione di 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
Utilizza lo strumento App Actions Test, una funzionalità del plug-in dell'Assistente Google per Android Studio, per testare i widget su un dispositivo fisico o virtuale. Per utilizzare dello strumento di test:
- Connetti il dispositivo di test all'app in esecuzione.
- In Android Studio, vai a Strumenti > Azioni app > Test Azioni app strumento.
- Fai clic su Crea anteprima.
- Con Android Studio, esegui l'app sul tuo dispositivo di test.
- Usa l'app Assistente sul dispositivo di test per testare l'Azione app. Per Ad esempio, puoi dire "Hey Google, per quanti chilometri ho corso su ExampleApp?"
- Osserva il comportamento della tua app o utilizza il debugger di Android Studio per verificare il risultato dell'azione desiderata.
Norme sulla qualità
Questa sezione evidenzia i requisiti chiave e le best practice quando puoi integrare le Azioni app con i widget.
Contenuti nei widget
- (Obbligatorio) Non mostrare gli annunci nei widget.
- Concentra completamente i contenuti del widget sul raggiungimento dell'intento. Azioni sconsigliate prova a soddisfare più intenti con un solo widget o aggiungi contenuti irrilevanti.
Gestire l'autenticazione
- (Obbligatorio) Se è necessaria l'autenticazione dell'utente per completare una procedura, restituire un widget che spiega che l'utente deve continuare nell'app. L'autenticazione utente incorporata nell'Assistente Google non è supportata per l'app Azioni.
- Se gli utenti consentono alla tua app di mostrare dati tramite i widget, puoi restituire un widget degli errori in fase di runtime per gli utenti non autorizzati.
Intent di riserva
(Obbligatorio) In
shortcuts.xml
, fornisci sempre un elemento di riserva<intent>
oltre al completamento del widget per una capacità assegnata. Un intent di riserva è un elemento<intent>
senza alcun requisito<parameter>
valori.Consente all'assistente di compiere un'azione quando la query dell'utente non contiene i parametri richiesti dall'altro fulfillment gli elementi definiti nella funzionalità. L'eccezione a questa regola è quando non sono parametri richiesti per quella funzionalità, nel qual caso solo il widget il completamento sia necessario.
Usa l'intent di riserva per aprire la tua app nella schermata pertinente non nella schermata Home.
Il seguente codice di un file shortcuts.xml
di esempio dimostra una
<capability>
con <intent>
di riserva a supporto di una principale
Evasione dell'ordine <app-widget>
:
<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
In questa sezione sono elencati i dati degli utenti finali raccolti dall'ultima versione del libreria dell'estensione Widgets.
Questo SDK invia risposte di sintesi vocale (TTS) fornite dallo sviluppatore che sono annunciati all'utente dall'Assistente Google tramite la voce dell'assistente tecnologia. Queste informazioni non vengono memorizzate da Google.
Le Azioni app potrebbero anche raccogliere i metadati dell'app client per i seguenti scopi:
- Per monitorare i tassi di adozione di diverse versioni dell'SDK.
- Per quantificare l'utilizzo delle funzionalità dell'SDK nelle app.