推送動態捷徑至 Google 助理

Android 捷徑可讓使用者快速執行動作或存取應用程式中的內容。Google 助理可在相關時機主動向使用者建議 Android 動態捷徑，讓使用者輕鬆探索並重播支援語音的功能。

舉例來說，您可以為使用者在記事應用程式中建立的每個記事推送捷徑。只要將 Google 捷徑整合 Jetpack 程式庫新增至專案，即可讓動態連結顯示在 Google 途徑 (例如 Google 助理) 上。這個程式庫可讓 Google 助理使用 ShortcutManagerCompat 類別擷取動態捷徑，而這是 ShortcutManager API 的 Jetpack 包裝函式。

在應用程式中使用 Google 捷徑整合程式庫時，您推送至 Google 的動態捷徑會顯示在 Google 助理應用程式中，做為語音捷徑建議。您可以使用 ShortcutManagerCompat 程式庫的 pushDynamicShortcut() 方法，將無限數量的動態捷徑推送至 Google 助理。

設定開發專案

要新增動態捷徑功能至應用程式，必須有 Google 捷徑整合程式庫，而這是一種 Android Jetpack 程式庫。本節說明如何設定應用程式開發專案以加入此程式庫。

如要新增此 Jetpack 程式庫並設定專案，請按照下列步驟操作：

  1. 更新 gradle.properties 檔案以處理 Jetpack 程式庫：

    gradle.properties

    android.useAndroidX=true
# Automatically convert third-party libraries to use AndroidX
android.enableJetifier=true

  2. 將 Jetpack 程式庫依附元件新增至 build.gradle：

    app/build.gradle

    dependencies {
 implementation "androidx.core:core:1.6.0"
 implementation "androidx.core:core-google-shortcuts:1.0.1"
 ...
}

    在上述程式碼範例中，您列出兩個 Jetpack 程式庫做為依附元件。androidx.core:core:1.6.0 程式庫包含 ShortcutManagerCompat 類別，可用來將動態捷徑推送至 Google。

    androidx.core:core-google-shortcuts:1.0.1 是 Google 捷徑整合程式庫。此程式庫不含任何開發人員專用 API。將此新增為依附元件後，Google 助理就能擷取您使用 ShortcutManagerCompat 類別推送的動態捷徑。

推送動態捷徑

如要推送符合資格，可在 Google 助理中顯示的動態捷徑，您必須先使用 ShortcutInfoCompat.Builder() 類別建立捷徑。

接著，您可以使用 ShortcutManagerCompat.pushDynamicShortcut() 方法。已推送捷徑 每當使用者在應用程式中完成相關動作時。下列範例 每當使用者在記事和清單應用程式中建立清單時，程式碼就會推送捷徑。

ExampleOrderActivity

Kotlin

// Define the dynamic shortcut for an item
var intent = Intent(context, DisplayOrderActivity::class.java)
intent.action = Intent.ACTION_VIEW
var shortcutInfo = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Running")
    .setLongLabel("Start running")
    .addCapabilityBinding(
        "actions.intent.CREATE_ITEM_LIST", "itemList.name", Arrays.asList("My First List")
    )
    .setIntent(intent) // Push the shortcut
    .build()

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo)

Java

// Define the dynamic shortcut for an item
Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat.Builder shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Running")
    .setLongLabel("Start running")
    .addCapabilityBinding(
      "actions.intent.CREATE_ITEM_LIST", "itemList.name", Arrays.asList("My First List"))
    .setIntent(intent)
    .build();

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

上述程式碼範例中，參考 ShortcutInfoCompat.Builder 方法的 id 會定義產生的捷徑物件 shortcutId。此id 必須是不重複的字串常值。詳情請參閱「Android 捷徑說明文件」。

在上述範例中，addCapabilityBinding 方法可將動態捷徑繫結至與 shortcuts.xml 中定義的相同 android:name capability。這個方法可讓您將捷徑與 語意內建意圖 (BII) 參數。

動態捷徑有時會在沒有特定 BII 參數的情況下推送 。使用者叫用時，Google 助理會觸發捷徑中定義的 intent 以執行動作。以下範例顯示沒有參數關聯的動態捷徑：

Kotlin

var intent: Intent = Intent(context, DisplayOrderActivity::class.java)
intent.setPackage(this, "com.sample.app")
intent.setAction(Intent.ACTION_VIEW)

var shortcutInfo: ShortcutInfoCompat = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Create a list")
    .setLongLabel("Create a list")
    .addCapabilityBinding("actions.intent.CREATE_ITEM_LIST")
    .setIntent(intent)
    .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

Java

Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setPackage(this, "com.sample.app");
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
  .setShortLabel("Create a list")
  .setLongLabel("Create a list")
  .addCapabilityBinding("actions.intent.CREATE_ITEM_LIST")
  .setIntent(intent)
  .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

透過 Google 助理測試動態捷徑

當 Google 助理成功地從應用程式擷取動態捷徑時，捷徑就符合資格，可在 Google 助理 Android 應用程式中顯示為語音捷徑建議。Google 助理應用程式會建議應用程式推送的最新捷徑。

如要使用 Google 助理測試動態捷徑，請按照下列步驟操作：

  1. 建立應用程式動作預覽畫面，並準備測試裝置，或 用於測試動作的模擬器 Google 助理外掛程式的安裝需求。
  2. 請開啟應用程式，並定義要推送的動態捷徑。然後完成動作。舉例來說，如果要在筆記應用程式中建立筆記時推送捷徑，那麼就請建立新的筆記。
  3. 在裝置上的「Assistant Settings」(Google 助理設定) 應用程式中開啟「Shortcuts」(捷徑)。動態捷徑會顯示在應用程式清單中。