透過應用程式動作，將 Android 應用程式擴充至 Google 助理 (第 2 級)

1. 總覽

應用程式動作可讓使用者直接從 Google 助理啟動特定的應用程式功能，協助您擴大 Android 應用程式的觸及範圍。Android 開發人員可以實作各項功能，讓 Google 助理瞭解使用者可用的功能類型，以及你希望如何執行這些要求。

在第一個應用程式動作程式碼研究室中，您已瞭解如何實作「健康與健身 BII」類別的內建意圖 (BII)，將 Google 助理擴充至範例健身應用程式。BII 分為多個類別，代表使用者經常要求 Google 助理執行的工作。

重要字詞：Google 助理的內建意圖，簡稱 BII，是預先定義的觸發條件，適用於使用者想執行的特定功能。Google 建構並維護 BII 的語言模型，以瞭解與該特定意圖相關的大量查詢變體。

在本程式碼研究室中，您將瞭解如何使用 BII 將應用程式動作新增至應用程式，詳情請參閱「Common」BII 類別，代表幾乎所有 Android 應用程式都能完成的常見應用程式工作。

本程式碼研究室說明使用應用程式動作進行開發的中級概念。您必須具備有開發 Android 應用程式和實作 Android 意圖的經驗。

建構項目

在本程式碼研究室中，您將兩組常見 BII 新增至範例待辦事項清單應用程式，讓使用者可以要求 Google 助理執行下列操作：

• 使用 actions.intent.OPEN_APP_FEATURE BII 瀏覽應用程式中的功能。
• 搭配 actions.intent.GET_THING BII 使用應用程式內搜尋功能來搜尋內容。

注意：需要具備搜尋功能的應用程式才能實作 actions.intent.GET_THING BII。進一步瞭解應用程式動作的部署規定。

圖 1. 三個漸進式畫面，其中 Google 助理在應用程式中顯示進行中的工作。

課程內容

您將瞭解如何使用通用類別 BII，將 Google 助理擴充至大多數的 Android 應用程式。此外，您也會學習如何使用 Android Studio 適用的 Google 助理外掛程式測試通用 BII。

必要條件

• 終端機指令，可在已安裝 Git 的情況下執行殼層指令。
• 最新的 Android Studio 穩定版。
• 擁有可存取 Google Play 商店的實體或虛擬 Android 裝置，用來測試你的動作。
• 您的 Google 帳戶必須登入 Android Studio，並在測試裝置上同時支援 Google 應用程式和 Google 助理應用程式。

注意：您可以在少數語言代碼中，透過 Google 助理測試本程式碼研究室所述的應用程式動作。請參閱常見 BII 參考文件，根據語言代碼瞭解哪些可用的意圖。

在本程式碼研究室中，您將使用 Android 裝置 (實體或虛擬) 來測試動作。如果使用實體裝置，請確認該裝置已連線至您的本機開發機器。此外，您也必須使用相同的 Google 帳戶登入裝置上的 Google 應用程式，並登入 Android Studio。此外，裝置也必須安裝 Google 助理應用程式。

2. 瞭解運作方式

應用程式動作會將 Google 助理使用者連結至您的 Android 應用程式。該怎麼做呢？

使用者向 Google 助理表明想使用應用程式時，Google 助理會從 shortcuts.xml 檔案中尋找應用程式註冊的應用程式動作。這個檔案內含應用程式的功能，可將 Google 助理的內建意圖或自訂意圖連結至 Android 意圖或深層連結。

重要詞彙：功能是您在 shortcuts.xml 中定義的範本，用於宣告使用者可在啟動應用程式後直接執行特定工作的動作類型。詳情請參閱「Android 說明文件」。

當使用者向 Google 助理下達查詢時，Google 助理會剖析使用者的輸入內容，並與應用程式動作意圖進行比對 (在本程式碼研究室中，為 BII)。Google 助理知道 Android 應用程式的 shortcuts.xml 檔案支援哪些功能。使用意圖比對時，該 BII 的功能包含您執行要求的方式。在本程式碼研究室中，執行要求是一種 Android 意圖，可在應用程式中啟動活動。

下圖顯示這個 Google 助理流程：

圖 2.說明 Google 助理如何處理語音查詢的流程。

shortcuts.xml 專案檔案內含每個應用程式動作的資訊，包括：

• 應用程式動作使用的內建意圖或自訂意圖
• 應為使用者提供哪些 Android 活動或深層連結
• 如何將內建意圖對應的參數與使用者提供給 Google 助理的資訊相互對應

接著，您的 Android 活動會篩選並處理所提供的 Android 意圖或深層連結，為使用者提供所需功能。這屬於使用者體驗，Google 助理會根據使用者的查詢叫用您的應用程式功能。

3. 準備開發環境

本程式碼研究室會使用 Android 的待辦事項清單範例應用程式。此範例應用程式可將項目新增至待辦事項清單、依類別搜尋項目，以及查看已完成工作的相關資訊。

下載基礎檔案

執行下列指令，複製範例應用程式的 GitHub 存放區：

git clone --branch codelab-start https://github.com/actions-on-google/appactions-common-biis-kotlin.git

複製存放區後，請按照下列步驟在 Android Studio 中開啟：

1. 在「Welcome to Android Studio」對話方塊中，按一下「Import project」。
2. 找出並選取您複製存放區的資料夾。

如要查看代表完成程式碼研究室的應用程式版本，請使用 --branch master 旗標複製範例應用程式存放區。

更新 Android 應用程式 ID

更新應用程式的應用程式 ID 可在測試裝置上辨識應用程式，避免「套件名稱重複」錯誤訊息。如要更新應用程式 ID，請開啟 app/build.gradle：

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

取代「MYUNIQUENAME」在 applicationId 欄位中使用不重複的值。

注意：更新 applicationId 後，您會收到「Gradle files have changed since last project sync...」警告。按一下「Sync Now」，避免上傳應用程式時發生問題。

在裝置上測試應用程式

對應用程式進行其他變更前，建議您先瞭解範例應用程式的功能。如要在模擬器上執行應用程式，請按照下列步驟操作：

1. 在 Android Studio 中，選取「Run」>「Run app」，或按一下工具列中的「Run」。
2. 在「Select Deployment Target」對話方塊中，選取裝置，然後按一下「OK」。雖然動作可在搭載 Android 5 (API 級別 21) 的裝置上執行，但建議使用 Android 10 (API 級別 30) 以上的 OS 版本。
3. 長按「主畫面」按鈕，即可設定 Google 助理並驗證其是否能正常運作。如果你尚未在裝置上登入 Google 助理，請先登入。

如要進一步瞭解 Android 虛擬裝置，請參閱「建立及管理虛擬裝置」。

圖 3. 展示待辦事項清單範例應用程式的動畫。

簡短探索這個應用程式的功能。輕觸「加號」圖示會建立一個新的工作項目，而右上方的選單項目則可讓您依完成狀態搜尋及篩選工作項目。

安裝測試外掛程式

您可以利用 Google 助理外掛程式，在測試裝置上測試應用程式動作。如果您還沒有測試工具，請按照下列步驟安裝：

1. 前往「檔案」>「設定」 (在 MacOS 中為 Android Studio >「Preferences」)。
2. 在「外掛程式」部分中，前往「Marketplace」並搜尋「Google 助理」。您也可以手動下載並安裝測試工具。
   • 如果在 Marketplace 上找不到外掛程式，請手動下載外掛程式，然後按照從磁碟安裝外掛程式的說明操作。
3. 安裝工具，然後重新啟動 Android Studio。

注意：測試外掛程式會透過 Android 裝置上的 Google 應用程式，將資訊傳送給 Google 助理。

4. 新增「取得 Thing BII」功能

actions.intent.GET_THING BII 會將應用程式內搜尋功能擴充至 Google 助理。在這個步驟中，您將實作及測試 GET_THING BII，讓使用者能夠在範例應用程式中搜尋特定工作。

提示：GET_THING BII 是用來搜尋在應用程式中使用預設應用程式內搜尋功能的內容或實體。使用 thing.name 意圖參數在搜尋條件中填入內容或實體名稱，然後向使用者顯示最相關的搜尋結果。

定義「取得 Thing」功能

在與搜尋相關的應用程式動作期間，Google 助理會從使用者查詢內容擷取搜尋字詞，並傳遞至 thing.name BII 參數，然後將該值傳遞至 Android 應用程式。

如要將 GET_THING BII 新增至應用程式，請更新位於 app/src/main/res/xml 範例專案目錄的 shortcuts.xml，並在頂層 <shortcuts> 標記中加入 <capability> 元素：

shortcuts.xml

<shortcuts ....>
    <capability android:name="actions.intent.GET_THING">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.yourApplicationId.appaction"
            android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
            <parameter
                android:name="thing.name"
                android:key="q"/>
        </intent>
    </capability>
</shortcuts>

上述設定：

1. 宣告應用程式回應 GET_THING BII。
2. 指定如何建構 Android 意圖，以回應該 BII，啟動應用程式。
   • 活動是使用 targetPackage 和 targetClass 識別的。
   • BII 參數 thing.name 對應至名為 q 的「Extra」意圖。

應用程式的資訊清單裡必須要有且已匯出的活動。

提供的 Android 應用程式含有中繼資料，因此 AndroidManifest 能順利辨識 shortcuts.xml 檔案：

<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />

測試應用程式動作

如要透過 Google 助理測試應用程式的應用程式內搜尋功能，請按照下列步驟操作：

1. 確認 Android 裝置已連線。
2. 前往「工具」>Google 助理 >應用程式動作測試工具。
3. 按一下「建立預覽」，接受「應用程式名稱」和「語言代碼」的預設值。如果收到系統提示，請詳閱並接受應用程式動作政策和服務條款。
4. 在工具要求您選取並設定 BII 的第一個步驟中，請選取 actions.intent.GET_THING。將 name 值從 running shoes 變更為 milk。
5. 按一下「Run App Action」。

在這項測試中，GET_THING BII 使用 name 屬性在應用程式中搜尋含有「牛奶」的工作。和先前的應用程式動作一樣，您可以使用測試工具來測試動作，或對測試裝置說出「Ok Google，在工作清單中搜尋蛋糕組合」或其他搜尋詞組。

提示：如果在執行測試工具時遇到問題，請參閱疑難排解指南。

5. 新增開啟應用程式功能 BII 功能

在這個步驟中，您將實作開啟應用程式功能 BII，讓使用者透過 Google 助理查看進行中和已完成的工作。為此，請在 shortcuts.xml 中完成功能，其中包含功能觸發方式、參數傳遞方式，以及要叫用哪些 Android 意圖的資訊。在本程式碼研究室中，您將使用 OPEN_APP_FEATURE BII。實作這個 BII 後，您將在裝置上測試動作。

注意：這個 BII 會啟動應用程式的功能。這項意圖特別實用，有助於使用者前往應用程式中可能難以找到的功能，或需要輕觸多次才能使用功能。您必須為功能參數指定內嵌目錄。

新增「開啟應用程式」功能

在 shortcuts.xml 的「Get Thing Capability」元素下方，新增用於開啟應用程式功能的第二個功能：

shortcuts.xml

<capability android:name="actions.intent.OPEN_APP_FEATURE">
   <intent
       android:action="android.intent.action.VIEW"
       android:targetPackage="yourApplicationId"
       android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
       <parameter
           android:name="feature"
           android:key="feature"/>
   </intent>
</capability>

這項功能會對應開啟應用程式功能 BII 和 Android 意圖，因此當觸發開啟應用程式功能時，Android 意圖就會觸發。

在觸發 Android 意圖之前，系統會從使用者的輸入內容提取支援的參數。OPEN_APP_FEATURE BII 支援 feature 參數，代表從使用者查詢內容中擷取的應用程式功能。這個應用程式支援以下兩種功能：進行中的工作和已完成的工作。使用者可以利用這些功能開啟應用程式，並在其中篩選工作清單。您需要使用內嵌目錄支援這些功能。

重要詞彙：內嵌清查，藉由提供一組應用程式可以解讀的實體來提供 BII 參數，以便擷取 BII 的實體。詳情請參閱「應用程式動作內嵌目錄」。

使用內嵌目錄處理意圖參數

意圖參數代表從使用者查詢內容中擷取的元素。例如，如果使用者說「Ok Google，用範例應用程式點一份披薩」，Google 助理就會擷取「披薩」加進 food.item schema.org 意圖參數，並將該參數傳送至要處理的動作。

開啟應用程式功能 BII 支援一個參數 feature，代表從使用者查詢內容中擷取的應用程式功能。這個參數必須使用內嵌目錄，以便 Google 助理提供一組支援的應用程式功能名稱，以比對參數值。

如要處理 feature 意圖參數，請在 shortcuts.xml 的「開啟應用程式」功能功能上方，加入下列程式碼的捷徑：

shortcuts.xml

<shortcut
   android:shortcutId="active_tasks"
   android:shortcutShortLabel="@string/label_active"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/active_tasks_synonyms" />
   </capability-binding>
</shortcut>

<shortcut
   android:shortcutId="completed_tasks"
   android:shortcutShortLabel="@string/label_completed"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/completed_tasks_synonyms" />
   </capability-binding>
</shortcut>

在上述程式碼中，您已定義內嵌目錄，以 shortcut 元素表示具有功能和參數繫結。捷徑可用來做為 BII 參數的目錄。Google 助理比對使用者查詢內容和快速指令的參數繫結值。如果是相符的參數值，系統會將 shortcutId 新增至執行要求意圖。當使用者透過要求啟用 OPEN_APP_FEATURE BII 時，Google 助理會比對功能參數值和捷徑的值屬性，然後在 Extra 中以 parameter 的形式將值傳遞至 targetClass。

舉例來說，如果使用者說出「Ok Google，在範例應用程式中顯示已完成的工作」這類指令，Google 助理就會比對功能意圖參數值「已完成的工作」，並將該值傳遞至 OPEN_APP_FEATURE 功能。接著，Google 助理會觸發 Android 意圖。

測試應用程式動作

在開發與測試期間，您可以使用 Google 助理外掛程式，在測試裝置上預覽 Google 助理應用程式動作。您也可以使用這項工具調整應用程式動作的意圖參數，測試動作如何處理使用者要求 Google 助理執行該動作的各種方式。

如要使用測試工具測試應用程式動作，請按照下列步驟操作：

1. 連接實體 Android 測試裝置，或啟動 Android 模擬器
2. 如果沒看到測試工具，請依序前往「Tools」>「Tools」開啟。Google 助理 >應用程式動作測試工具。
3. 按一下「更新」按鈕，即可重新整理預覽畫面。
4. 在工具要求您選取並設定 BII 的第一個步驟中，請選取 actions.intent.OPEN_APP_FEATURE。
5. 在「feature」方塊中，將 History 的預設值更新為 Completed tasks。
6. 按一下「Run App Action」。

提示：如果在執行測試工具時遇到問題，請參閱疑難排解指南。

或者，你也可以直接在裝置的 Google 助理應用程式中，使用叫用名稱來試用應用程式動作。舉例來說，您可以說「Ok Google，在工作清單中顯示已完成的工作」。

6. 後續步驟

恭喜！

您現在可以使用通用 BII，讓幾乎所有 Android 應用程式都能與 Google 助理搭配使用。

涵蓋內容

在本程式碼研究室中，您已瞭解以下內容：

• 如何讓使用者透過 Google 助理深入探索特定的應用程式功能。
• 使用者如何透過 Google 助理使用應用程式內搜尋功能。
• 如何使用 Google 助理外掛程式測試常見的 BII。

後續步驟

您可以嘗試進一步修正待辦事項清單應用程式。如要參照完成的專案，請查看 GitHub 上的存放區 –master 分支版本。

歡迎參考下列建議，進一步瞭解如何利用應用程式動作擴充這個應用程式：

• 請參閱使用 Google Analytics for Firebase 的待辦事項清單範例，瞭解如何追蹤應用程式動作成效。
• 請參閱應用程式動作的內建意圖參考資料，探索更多將應用程式擴充至 Google 助理的方式。

如要繼續進行 Actions on Google 流程，請參閱下列資源：

• developers.google.com/assistant：Actions on Google 官方文件網站。
• 應用程式動作範例索引：探索應用程式動作功能的範例應用程式和程式碼。
• Actions on Google GitHub 存放區：程式碼範例和程式庫。
• r/GoogleAssistantDev：專為使用 Google 助理的開發人員提供的官方 Reddit 社群。

在 Twitter 上追蹤 @ActionsOnGoogle，以隨時掌握最新公告，並透過 Twitter 發文給 #AoGDevs 分享你的成果！

意見調查

最後，請填寫這份問卷調查，與我們分享您使用本程式碼研究室的感想。