Integrate App Actions with Android widgets

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

}

Launcher pinning

This library enables the Add this widget button to be displayed with your widget in Assistant. Pinning requires adding the following receiver definition to AndroidManifest.xml:

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>

Inventory availability

BIIs supporting inline inventory or web inventory can extend these inventories to your widget fulfillments.

Inline inventory

The following code sample demonstrates a START_EXERCISE BII capability configured for inline inventory and widget fulfillment:

shortcuts.xml

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

In the preceding sample, when a user triggers this capability by asking Assistant, “Start running with ExampleApp ”, the option bundle for the <app-widget> fulfillment will contain the following key-value pair:

• Key = “exerciseName”
• Value = “RunningShortcut”

Web inventory

See the following sample code for a capability enabled for web inventory and widget fulfillment:

shortcuts.xml

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

Testing

Use the App Actions Test Tool, a feature of the Google Assistant plugin for Android Studio, to test widgets on a physical or virtual device. To use the test tool, follow these steps:

1. Connect your test device with your app running.
2. In Android Studio, go to Tools > App Actions > App Actions Test Tool.
3. Click Create preview.
4. In Android Studio, run your app on your test device.
5. Use the Assistant app on your test device to test your App Action. For example, you can say something like "Hey Google, how many miles have I run this week on ExampleApp?".
6. Observe the behavior of your app, or use the Android Studio debugger, to verify the desired action result.

Quality guidelines

This section highlights key requirements and best practices when you integrate App Actions with widgets.

Content in widgets

• (Required) Do not show ads in your widgets.
• Widget content should be completely focused on fulfilling the intent — don't try to fulfill multiple intents with one widget, or add irrelevant content.

Handling authentication

• (Required) Where user authentication is needed to complete a user flow, return a widget that explains that the user needs to continue in the app. In-line user authentication in Google Assistant is not supported for App Actions.
• If users are permitting your app to show data via widgets, you can return an error widget at runtime for unauthorized users.

Fallback intents

• (Required) In your shortcuts.xml, always provide a fallback <intent> in addition to your widget fulfillment for a given capability. A fallback intent is an <intent> element with no required <parameter> values. This enables Assistant to fulfill an Action when the user query does not contain parameters required by the other fulfillment elements defined in the capability. The exception to this is when there are no required parameters for that capability, in which case only the widget fulfillment is needed.
• The fallback intent should open your app to the relevant screen in your app, not the home screen.

The following sample code demonstrates a <capability> with a fallback <intent> supporting a primary <app-widget> fulfillment:

shortcuts.xml

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

Google Play Data Disclosure

This section lists the end-user data collected by the latest version of the Widgets Extension library.

This SDK sends developer-provided text-to-speech (TTS) responses that are announced to the user by Google Assistant using Assistant’s speech technology. This information is not stored by Google.

App actions may also collect client app metadata for the following purposes:

• To monitor adoption rates of different SDK versions.
• To quantify SDK features usage across apps.