整合應用程式動作與 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);
    }

}

啟動器釘選

這個程式庫可讓系統在 Google 助理內的小工具旁邊顯示「新增這個小工具」按鈕。您必須將以下接收器定義加入 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>

在上述範例中，當使用者要求 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 助理在使用者查詢內容內並無功能內定義的其他執行要求元素所需的參數時，依然可以執行動作。當該功能並無所需的參數時，則不在此限，這種情況只需要小工具執行要求。
• 備用意圖應該開啟您的應用程式，並進入相關的應用程式畫面，而不是主畫面。

以下程式碼會展示設有支援主要 <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 資料揭露

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

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

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

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