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

1. 總覽

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

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

關鍵字：Google 助理內建意圖 (簡稱 BII) 是預先定義的觸發條件，可觸發使用者想執行的特定功能。Google 會建立及維護 BII 的語言模型，以便瞭解與該特定意圖相關的大量查詢變化。

在本程式碼研究室中，您將瞭解如何使用「Common」BII 類別的 BII，將應用程式動作新增至應用程式。這類別代表幾乎任何 Android 應用程式都能執行的常見應用程式工作。

本程式碼研究室涵蓋應用程式動作開發的中級概念。您應具備開發 Android 應用程式和實作 Android Intent 的經驗。

建構項目

在本程式碼研究室中，您會將兩個常見 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 的終端機，可執行 Shell 指令。
• 最新的 Android Studio 穩定版。
• 可存取 Google Play 商店的實體或虛擬 Android 裝置，用於測試動作。
• 您必須登入 Android Studio，並在測試裝置上登入 Google 應用程式和 Google 助理應用程式，且登入的 Google 帳戶必須相同。

注意：您可以在少數語言代碼中，使用 Google 助理測試本程式碼研究室中說明的應用程式動作。請參閱常見 BII 參考文件，瞭解各個地區可用的意圖。

在本程式碼研究室中，您會使用 Android 裝置 (實體或虛擬) 測試動作。如果使用實體裝置，請確認裝置已連上本機開發電腦。您也必須使用相同的 Google 帳戶登入 Android Studio 和裝置上的 Google 應用程式。裝置也必須安裝 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，即可在測試裝置上清楚識別應用程式，並避免在將應用程式上傳至 Play 管理中心時發生「套件名稱重複」錯誤。如要更新應用程式 ID，請開啟 app/build.gradle：

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

將 applicationId 欄位中的「MYUNIQUENAME」替換為專屬名稱。

注意：更新 applicationId 後，Android Studio 會顯示「Gradle files have changed since last project sync...」警告。按一下「立即同步」，避免上傳應用程式時發生問題。

在裝置上測試應用程式

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

1. 在 Android Studio 中，依序選取「Run」>「Run app」，或按一下工具列中的「Run」圖示 。
2. 在「Select Deployment Target」對話方塊中，選取裝置並按一下「OK」。建議使用 Android 10 (API 級別 30) 以上版本，不過動作最多可以支援到 Android 5 (API 級別 21) 的裝置。
3. 長按「主畫面」按鈕設定 Google 助理，並確認是否正常運作。如果尚未登入，請先在裝置上登入 Google 助理。

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

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

簡單瀏覽應用程式，瞭解其功能。輕觸「加號」圖示即可建立新工作項目，右上方的選單項目則可供您依完成狀態搜尋及篩選工作項目。

安裝測試外掛程式

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

1. 依序前往「File」>「Settings」 (MacOS 中為「Android Studio」>「Preferences」)。
2. 在「Plugins」部分，前往「Marketplace」Marketplace並搜尋「Google Assistant」。您也可以手動下載及安裝測試工具。
   • 如果找不到 Marketplace 中的外掛程式，請Marketplace手動下載外掛程式，然後按照「從磁碟安裝外掛程式」一文中的指示操作。
3. 安裝工具，然後重新啟動 Android Studio。

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

4. 新增 Get Thing BII 功能

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

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

定義「取得事物」功能

在搜尋相關的應用程式動作期間，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. 依序前往「Tools」>「Google Assistant」>「App Actions Test Tool」。
3. 按一下「建立預覽」，接受「應用程式名稱」和「語言代碼」的預設值。如果系統要求，請詳閱並接受應用程式動作政策和服務條款。
4. 在工具要求選取及設定 BII 的第一個步驟中，選取 actions.intent.GET_THING。將 name 值從 running shoes 變更為 milk。
5. 按一下「執行應用程式動作」。

在這項測試中，GET_THING BII 會使用 name 屬性，在應用程式中搜尋含有「牛奶」的任務。與先前的應用程式動作一樣，您可以使用測試工具測試動作，或直接在測試裝置上說出「Ok Google，在 Task List 中搜尋蛋糕粉」或其他搜尋詞組。

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

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

在這個步驟中，您會導入開啟應用程式功能 BII，讓使用者透過 Google 助理查看進行中和已完成的工作。如要完成這項功能，請在 shortcuts.xml 中填寫相關資訊，包括功能的觸發方式、參數的傳遞方式，以及要叫用的 Android intent。在本程式碼研究室中，您將使用 OPEN_APP_FEATURE BII。導入這項 BII 後，請在裝置上測試動作。

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

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

在「Get Thing Capability」元素下方的 shortcuts.xml 中，為「Open app」功能新增第二項功能：

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 intent。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 助理會將功能參數值與捷徑的值屬性相符，然後將值傳遞至 targetClass，做為 Extra 中的 parameter。

舉例來說，如果使用者說出「Ok Google，在 ExampleApp 中顯示已完成的工作」，Google 助理會將功能意圖參數值「已完成的工作」與對應的清查捷徑相符，並將該值傳遞至 OPEN_APP_FEATURE 功能。接著，Google 助理會觸發 Android 意圖。

測試應用程式動作

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

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

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

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

此外，您也可以在裝置上透過 Google 助理應用程式直接使用叫用名稱，藉此試用應用程式動作。例如，你可以說「Ok Google，在工作清單中顯示已完成的工作」。

6. 後續步驟

恭喜！

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

涵蓋內容

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

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

後續步驟

您可以在這裡嘗試進一步調整待辦事項應用程式。如要參考完成的專案，請前往 GitHub 上的存放區 –master 分支。

以下提供一些建議，協助您進一步瞭解如何使用應用程式動作擴充這個應用程式：

• 請參閱待辦事項範例 (搭配 Google Analytics for Firebase)，瞭解如何追蹤應用程式動作的成效。
• 如要進一步瞭解如何將應用程式擴充至 Google 助理，請參閱應用程式動作內建意圖參考資料。

如要繼續使用 Google 助理開發動作，請參閱下列資源：

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

在 Twitter 上追蹤 @ActionsOnGoogle，隨時掌握最新公告，並在推文中加上 #AoGDevs，分享您開發的內容！

意見調查

最後，請填寫這份問卷，提供您對本程式碼研究室的意見。