Cómo integrar Acciones en apps con widgets de 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);
    }

}

Recomendaciones de estilo de TTS

Usa las siguientes recomendaciones de estilo para optimizar las introducciones de widgets personalizados para TTS y mensajes visibles.

Fijación de selectores

La biblioteca de Widgets Extension permite que se muestre el botón para agregar el widget con tu widget en Asistente. Para habilitar la fijación, agrega la siguiente definición del receptor 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>

Disponibilidad de inventario

Los BIIs que admiten inventario intercalado o inventario web pueden extender estos inventarios a tus entregas de widgets.

Inventario intercalado

En el siguiente código de un archivo shortcuts.xml de muestra, se muestra una función de BII START_EXERCISE configurada para el inventario intercalado y la entrega de widgets:

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

En el ejemplo anterior, cuando un usuario pide al Asistente: "Comienza a ejecutar con AppDeEjemplo". El paquete de opciones para la entrega de <app-widget> contendrá el siguiente par clave-valor:

• Clave = “exerciseName”
• Valor = “RunningShortcut”

Inventario web

En el siguiente código de un archivo shortcuts.xml de muestra, se muestra una función habilitada para el inventario web y la entrega de widgets:

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

Prueba las Acciones en apps

Usa la herramienta de pruebas de Acciones en apps, una función del complemento de Asistente de Google para Android Studio, para probar widgets en un dispositivo físico o virtual. Para usar esa herramienta, sigue estos pasos:

1. Conecta el dispositivo de prueba a la app en ejecución.
2. En Android Studio, ve a Tools > App Actions > App Actions Test Tool.
3. Haz clic en Create Preview.
4. En Android Studio, ejecuta la app en tu dispositivo de prueba.
5. Usa la app de Asistente en tu dispositivo de prueba para probar la Acción en la app. Por ejemplo, puedes decir "Hey Google, ¿cuántos kilómetros corrí esta semana en AppDeEjemplo?".
6. Observa el comportamiento de tu app o usa el depurador de Android Studio a fin de verificar el resultado de la acción que deseas.

Lineamientos de calidad

En esta sección, se destacan los requisitos fundamentales y las prácticas recomendadas para la integración de Acciones en apps con widgets.

Contenido en widgets

• No muestres anuncios en tus widgets. (Obligatorio)
• Enfoca el contenido del widget por completo en entregar el intent. No intentes entregar varios intents con un widget ni agregues contenido irrelevante.

Cómo controlar la autenticación

• En los casos en que se necesite la autenticación para completar un flujo de usuarios, muestra un widget que explique que el usuario debe continuar en la app. La autenticación intercalada de usuarios en Asistente de Google no es compatible con Acciones en apps. (Obligatorio)
• Si los usuarios permiten que la app muestre datos con widgets, puedes mostrar un widget de error en el tiempo de ejecución a los usuarios no autorizados.

Intents de resguardo

• En tu archivo shortcuts.xml, siempre proporciona un <intent> de resguardo además de la entrega de widgets para una función determinada. (Obligatorio) Un intent de resguardo es un elemento <intent> sin valores de <parameter> obligatorios.

  Esto permite que Asistente realice una acción cuando la consulta del usuario no contenga parámetros requeridos por los otros elementos de entrega definidos en la función. La excepción se da cuando no hay parámetros obligatorios para esa función, en cuyo caso solo se necesita la entrega del widget.

• Usa el intent de resguardo para abrir la app en la pantalla relevante, no en la pantalla principal.

En el siguiente código de un archivo shortcuts.xml de muestra, se muestra una <capability> con un resguardo <intent> que admite una entrega principal de <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>

Divulgación de datos de Google Play

En esta sección, se muestra la recopilación de datos del usuario final de la versión más reciente de la biblioteca de Widgets Extension.

Este SDK envía respuestas de texto a voz (TTS) proporcionadas por el desarrollador, que Asistente de Google anuncia al usuario con la tecnología de voz de Asistente. Google no almacena esta información.

Las Acciones en apps también pueden recopilar metadatos de la app cliente para los siguientes fines:

• Supervisar las tasas de adopción de diferentes versiones del SDK
• Cuantificar el uso de las funciones del SDK en las apps