Integrazione di Azioni app con i widget Android

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:

1. Rilevamento: visualizza in modo proattivo i widget in risposta alle richieste degli utenti. query in linguaggio naturale.
2. Coinvolgimento: mostra widget in contesti in vivavoce, ad esempio quando L'assistente fornisce risultati personali nella schermata di blocco e su Android Auto.
3. 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:

1. Implementa un widget Android seguendo i passaggi descritti in Crea un widget semplice.
2. 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.
3. 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:

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 corso AppWidgetProvider 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:

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

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

dependencies {
    //...
    implementation "com.google.assistant.appactions:widgets:0.0.1"
}

import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

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

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

}

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

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

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

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