App Actions を 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);
    }

}

ランチャーの固定

このライブラリを使用すると、[このウィジェットを追加] ボタンをアシスタント内のウィジェットとともに表示できます。固定するには、次のレシーバー定義を 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>

インベントリの可用性

インライン インベントリまたはウェブ インベントリをサポートする BII は、これらのインベントリをウィジェット フルフィルメントに拡張できます。

インライン インベントリ

次のコードサンプルは、インライン インベントリとウィジェット フルフィルメント用に構成された START_EXERCISE BII のケーパビリティを示しています。

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>

前述のサンプルで、ユーザーがアシスタントに「ExampleApp でランニングを始めて」と話しかけてこのケーパビリティをトリガーすると、<app-widget> フルフィルメントのオプション バンドルには次の Key-Value ペアが含まれます。

• キー = “exerciseName”
• 値 = “RunningShortcut”

ウェブ インベントリ

ウェブ インベントリとウィジェット フルフィルメントに対して有効になっているケーパビリティについては、以下のサンプルコードをご覧ください。

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>

テスト

Android Studio 用の Google アシスタント プラグインの機能である App Actions Test Tool を使用して、実機または仮想デバイスでウィジェットをテストします。このテストツールを使用する手順は次のとおりです。

1. アプリを実行中のテストデバイスを接続します。
2. Android Studio で、[Tools] > [App Actions] > [App Actions Test Tool] に移動します。
3. [Create preview] をクリックします。
4. Android Studio から、テストデバイスでアプリを実行します。
5. テストデバイスのアシスタント アプリを使用して、App Action をテストします。たとえば、「OK Google, 今週は ExampleApp で何マイル走った？」と尋ねます。
6. アプリの動作を観察します。または、Android Studio デバッガを使用して、アクションの結果が想定どおりになることを確認します。

品質に関するガイドライン

このセクションでは、App Actions をウィジェットと統合する際の主な要件とおすすめの方法について説明します。

ウィジェットのコンテンツ

• （必須）ウィジェットに広告を表示しないでください。
• ウィジェットのコンテンツは、インテントのフルフィルメントのみに完全に集中させる必要があります。1 つのウィジェットで複数のインテントを遂行しないでください。また、無関係なコンテンツを追加しないでください。

認証の処理

• （必須）ユーザーフローを完了するためにユーザー認証が必要な場合は、ユーザーが操作を続行する必要があることを説明するウィジェットをアプリ内で返してください。Google アシスタント内のインライン ユーザー認証は、App Actions ではサポートされていません。
• ユーザーがウィジェットを介したデータの表示をアプリに許可している場合は、権限のないユーザーに対して実行時にエラー ウィジェットを返すことができます。

フォールバック インテント

• （必須）shortcuts.xml では、常に、特定のケーパビリティのウィジェット フルフィルメントに加えて、フォールバック <intent> を指定します。フォールバック インテントは、必須の <parameter> 値のない <intent> 要素です。これがあることにより、ユーザークエリに、ケーパビリティで定義された他のフルフィルメント要素に必要なパラメータが含まれていない場合に、アシスタントがアクションを実行できるようになります。ただし、そのケーパビリティに必要なパラメータがない場合は例外です。この場合、ウィジェット フルフィルメントのみが必要になります。
• フォールバック インテントは、ホーム画面ではなく、アプリ内の関連する画面にアプリを開く必要があります。

次のサンプルコードは、プライマリ <app-widget> フルフィルメントをサポートするフォールバック <intent> を備えた <capability> を示しています。

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 のデータ開示

このセクションでは、最新バージョンの Widgets Extension ライブラリによって収集されるエンドユーザー データを記載しています。

この SDK では、アシスタントの音声機能を使用して Google アシスタントがユーザーに読み上げる、デベロッパー提供のテキスト読み上げ（TTS）応答が送信されます。この情報が Google に保存されることはありません。

App Actions は、次の目的でクライアント アプリのメタデータを収集する場合があります。

• 各 SDK バージョンの導入率をモニタリングするため。
• アプリ全体での SDK 機能の使用状況を数量化するため。