Integrazione di Azioni app con i widget Android

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

}

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.

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:

1. Collega il dispositivo di test all'app in esecuzione.
2. In Android Studio, vai a Strumenti > Azioni app > Strumento di test di Azioni app.
3. Fai clic su Crea anteprima.
4. Esegui l'app sul dispositivo di test con Android Studio.
5. 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?"
6. 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.