整合應用程式動作與 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 的自訂小工具簡介和系統顯示的提示最佳化。

啟動器釘選功能

借助小工具擴充功能程式庫，您可以在 Google 助理內的小工具旁邊顯示「新增這個小工具」按鈕。如要啟用釘選功能，請將下列接收器定義加入 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>

在上述範例中，當使用者要求 Google 助理「開始執行範例應用程式」，並觸發此功能時，<app-widget> 執行要求的選項組合會包含以下鍵/值組合：

• 鍵 = “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 助理外掛程式的其中一項功能，可用來在實體或虛擬裝置上測試小工具。如要使用這個測試工具，請按照下列步驟操作：

1. 連結到執行您的應用程式的測試裝置。
2. 在 Android Studio 中，依序前往「Tools」>「App Actions」>「App Actions Test Tool」。
3. 按一下「Create preview」。
4. 在 Android Studio 中，使用您的測試裝置執行應用程式。
5. 在測試裝置上使用 Google 助理應用程式，測試應用程式動作。例如，您可以說：「Ok Google，根據範例應用程式的數據，我這個禮拜跑了幾英里？」。
6. 觀察應用程式行為，或使用 Android Studio 偵錯工具，確認是否達到想要的動作結果。

品質指南

本節特別說明整合應用程式動作與小工具時的重要必要條件和最佳做法。

小工具內容

• (必要條件) 您不得在小工具中顯示廣告。
• 小工具內容應該完全注重於如何執行意圖。請勿嘗試以單一小工具執行多項意圖，或加入不相關的內容。

處理身分驗證

• (必要條件) 如果使用者需通過驗證才能完成使用者流程，請傳回小工具，說明使用者需要在應用程式中繼續操作。「應用程式動作」不支援 Google 助理中的內嵌使用者驗證機制。
• 如果使用者允許應用程式透過小工具顯示資料，您可以在執行階段期間，為未經授權的使用者傳回錯誤小工具。

備用意圖

• (必要條件) 在 shortcuts.xml 中，每個功能皆需在小工具執行要求之外，提供備用的 <intent>。備用意圖是 <intent> 元素，不需提供 <parameter> 值。

  這樣一來，儘管在功能內定義的其他執行要求元素需要使用參數，但使用者查詢內容中不含該參數，Google 助理依然可以執行動作。如果該功能沒有必要參數，則不在此限，此時只需要小工具執行要求就夠了。

• 請使用備用意圖，將應用程式開啟至相關畫面，而非主畫面。

歡迎參考 shortcuts.xml 範例檔案中的以下程式碼，瞭解 <capability> 如何搭配備用 <intent> 支援主要的 <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>

Google Play 資料揭露

本節明列最新版小工具擴充功能程式庫會收集哪些使用者資料。

這個 SDK 會傳送由開發人員提供的文字轉語音 (TTS) 回應，讓 Google 助理使用助理語音技術為使用者朗讀這段回應。Google 不會儲存這項資訊。

應用程式動作也可能會為了以下目的而收集用戶端應用程式的中繼資料：

• 監控不同 SDK 版本的採用率。
• 量化分析各應用程式之間的 SDK 功能使用情形。