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

}

TTS スタイルに関する推奨事項

TTS および表示されるプロンプトに最適なカスタム ウィジェットを導入するには、次のスタイルの推奨事項を適用します。

ランチャーの固定

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

インライン インベントリ

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

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

App Actions をテストする

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> 要素です。

  これがあることにより、ユーザークエリに、ケーパビリティで定義された他のフルフィルメント要素に必要なパラメータが含まれていない場合に、アシスタントがアクションを実行できるようになります。ただし、そのケーパビリティに必要なパラメータがない場合は例外です。この場合、ウィジェット フルフィルメントのみが必要になります。

• フォールバック インテントを使用して、ホーム画面ではなく関連する画面にアプリを開きます。

サンプル shortcuts.xml ファイルの次のコードは、メインの <app-widget> フルフィルメントをサポートするフォールバック <intent> がある <capability> を示しています。

<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 機能の使用状況を数量化するため。