Integrar as Ações no app com widgets do 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);
    }

}

Recomendações de estilo para TTS

Use as recomendações de estilo a seguir para otimizar as apresentações do widget personalizado para o TTS e as solicitações exibidas.

Fixação na tela de início

A biblioteca Widgets Extension permite que o botão Add this widget seja mostrado com seu widget no Google Assistente. Para ativar a fixação, adicione a seguinte definição de 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>

Disponibilidade de inventário

As BIIs com suporte ao inventário inline ou ao inventário da Web podem ampliar esses inventários para os fulfillments do widget.

Inventário inline

O código a seguir de um arquivo shortcuts.xml de exemplo demonstra um recurso da BII START_EXERCISE configurado para inventário inline e fulfillment do 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>

No exemplo anterior, quando um usuário pedir para o Google Assistente "Começar a correr com o ExampleApp", o pacote de opções para o fulfillment <app-widget> vai conter o seguinte par de chave-valor:

• Tecla = “exerciseName”
• Valor: “RunningShortcut”

Inventário da Web

O código a seguir de um exemplo de arquivo shortcuts.xml mostra um recurso ativado para inventário da Web e fulfillment do 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>

Testar Ações no app

Use a App Actions Test Tool (um recurso do plug-in do Google Assistente para Android Studio) para testar widgets em um dispositivo físico ou virtual. Siga estas etapas para usar a ferramenta de teste:

1. Conecte o dispositivo de teste em que o app está sendo executado.
2. No Android Studio, acesse Tools > App Actions > App Actions Test Tool.
3. Clique em Create preview.
4. No Android Studio, execute o app no dispositivo de teste.
5. Use o app Google Assistente no seu dispositivo para testar a ação no app. Por exemplo, você pode dizer algo como "Ok Google, quantos quilômetros eu corri esta semana no ExampleApp?".
6. Observe o comportamento do app ou use o depurador do Android Studio para verificar o resultado da ação desejada.

Diretrizes de qualidade

Esta seção destaca os principais requisitos e as práticas recomendadas quando você integra Ações no app com widgets.

Conteúdo em widgets

• (Obrigatório) Não mostre anúncios nos seus widgets.
• Concentre-se totalmente no conteúdo do widget para cumprir a intent. Não atenda a várias intents com um único widget nem adicione conteúdo irrelevante.

Processar a autenticação

• (Obrigatório) Quando a autenticação do usuário for necessária para concluir um fluxo do usuário, retorne um widget que explica que o usuário precisa continuar no app. As Ações no app não têm suporte para a autenticação de usuários inline no Google Assistente.
• Se os usuários permitirem que o app mostre dados usando widgets, você poderá retornar um widget de erro no tempo de execução para usuários não autorizados.

Intents substitutas

• (Obrigatório) No shortcuts.xml, sempre forneça uma <intent> substituta com o fulfillment do widget para um recurso específico. Uma intent substituta é um elemento <intent> sem valores de <parameter> obrigatórios.

  Isso permite que o Google Assistente realize uma ação quando a consulta do usuário não tiver parâmetros exigidos pelos outros elementos de fulfillment definidos no recurso. A exceção é quando não há parâmetros obrigatórios para o recurso. Nesse caso, apenas o fulfillment do widget é necessário.

• Use a intent de fallback para abrir o app na tela relevante, não na tela inicial.

O código a seguir de um exemplo de arquivo shortcuts.xml demonstra uma <capability> com uma <intent> substituta que oferece suporte a um fulfillment principal do <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>

Declaração sobre o uso de dados pelo Google Play

Esta seção lista os dados do usuário final coletados pela versão mais recente da biblioteca Widgets Extension.

Esse SDK envia as respostas de conversão de texto em voz (TTS) fornecidas pelo desenvolvedor que são ditas ao usuário pelo Google Assistente usando a tecnologia de fala dele. Essas informações não são armazenadas pelo Google.

As Ações no app também podem coletar metadados do app cliente para as seguintes finalidades:

• Monitorar as taxas de adoção de diferentes versões do SDK.
• Quantificar o uso dos recursos do SDK nos apps.