推送動態捷徑至 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 a menu item
var intent = Intent(context, DisplayOrderActivity::class.java)
intent.action = Intent.ACTION_VIEW
var shortcutInfo = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Cappuccino")
    .setLongLabel("Order another cappuccino")
    .addCapabilityBinding(
        "actions.intent.ORDER_MENU_ITEM", "menuItem.name", Arrays.asList("cappuccino")
    )
    .setIntent(intent) // Push the shortcut
    .build()

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

Java

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

ShortcutInfoCompat.Builder shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Cappuccino")
    .setLongLabel("Order another cappuccino")
    .addCapabilityBinding(
      "actions.intent.ORDER_MENU_ITEM", "menuItem.name", Arrays.asList("cappuccino"))
    .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("Order coffee")
    .setLongLabel("Order a cup of coffee")
    .addCapabilityBinding("actions.intent.ORDER_MENU_ITEM")
    .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("Order coffee")
  .setLongLabel("Order a cup of coffee")
  .addCapabilityBinding("actions.intent.ORDER_MENU_ITEM")
  .setIntent(intent)
  .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

透過 Google 助理測試動態捷徑

Google 助理成功從應用程式擷取動態捷徑後,就能在 Google 助理 Android 應用程式中,將該捷徑顯示為語音捷徑建議。Google 助理應用程式會建議應用程式推送的最新捷徑。

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

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