範例應用程式
如果使用 Google Home API 時遇到任何問題，可以收集記錄以進行進一步偵錯。如要從行動裝置收集記錄，必須使用 Android Debug Bridge (adb)。如果需要 Google 協助，請從 Android 裝置和中樞裝置收集記錄，並在問題追蹤器中開啟支援單，附上相關資訊和記錄。
收集 Android 記錄
行動裝置必須連線至本機，才能完成所有涉及 adb 的步驟。
安裝 adb
如果尚未在本機上設定 Android Debug Bridge，請按照下列步驟操作：
- 在電腦上安裝「adb」。
- 在 Android 手機上開啟「開發人員選項」和「USB 偵錯」。
Android Studio 專用 Google Home 外掛程式
Google Home Plugin for Android Studio 是收集及分析記錄的實用工具，專為 Google Home platform 開發人員而設計。這個外掛程式可讓您存取 Google Assistant Simulator、Cloud Logging 和其他工具，簡化 smart home 開發程序。
搭配使用這項工具和 adb，進一步分析Matter裝置記錄。
如要瞭解詳情及取得這項工具，請參閱Google Home Plugin for Android Studio。
版本資訊
建議您在決定收集記錄時，一併收集與設定相關的所有版本資訊。如要與 Google 分享問題，就必須提供這項資訊。
- 取得行動裝置 ID：
adb devicesList of devices attached device-id device
- 將這個值儲存在名為
phoneid的變數中：phoneid=device-id - 將各種裝置資訊儲存至變數：
containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep "versionName" || true); homemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home " || true); optionalhomemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.optional_home " || true); policyhomemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.policy_home" || true); threadinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.threadnetwork" || true); ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep versionName || true); enabledfeatures=$((adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "Enabled features" | grep -i "home") || true); androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true); androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true) - 將所有變數儲存到名為
_versions.txt的檔案：展開即可顯示將變數儲存至檔案的指令
您可以一次複製整個程式碼區塊，然後貼到終端機。
versionfile=$logtimestamp"_versions.txt" echo "Saving version info to $versionfile"
echo "Container version:" >> $versionfile echo $containerinfo >> $versionfile echo "" >> $versionfileecho "Home Module version:" >> $versionfile echo $homemoduleinfo >> $versionfile echo "" >> $versionfileecho "Optional Home Module version:" >> $versionfile echo $optionalhomemoduleinfo >> $versionfile echo "" >> $versionfileecho "Policy Home Module version:" >> $versionfile echo $policyhomemoduleinfo >> $versionfile echo "" >> $versionfileecho "Thread Module version:" >> $versionfile echo $threadinfo >> $versionfile echo "" >> $versionfileecho "GHA version:" >> $versionfile echo $ghainfo >> $versionfile echo "" >> $versionfileecho "Android version: " >> $versionfile echo $androidversion >> $versionfile echo "" >> $versionfileecho "Android API version: " >> $versionfile echo $androidapiversion >> $versionfile echo "" >> $versionfileecho "Found enabled features (blank if missing):" >> $versionfile echo $enabledfeatures >> $versionfile echo "" >> $versionfile - 確認
_versions.txt的內容：cat _versions.txt現在可以視需要將這個檔案提供給 Google，以利進行疑難排解。展開即可顯示範例檔案輸出內容
Container version: versionName=23.19.12 (190400-530524295) versionName=22.46.17 (190408-491726958)
Home Module version: com.google.android.gms.home [v230508900]Optional Home Module version:Policy Home Module version: com.google.android.gms.policy_home [230508900] [230508900065.505615668.505615668] [Download:000003be/dl-Home.integ_230508900100400.apk] [download:/Home.integ/230508900100400:Home.integ:230508900100400]Thread Module version: com.google.android.gms.threadnetwork [v231912000]GHA version: versionName=3.2.32.1Android version: 13Android API version: 33Found enabled features (blank if missing):
收集記錄
如要收集記錄，請關閉行動裝置上執行的所有應用程式。然後執行下列步驟：
- 開啟終端機視窗，然後清除現有的裝置記錄：
adb logcat -b all -c - 開始收集記錄程序：
adb logcat >> _logs.txt - 執行範例應用程式，並擷取所有使用者介面動作。完成後，請按下 Ctrl+C (或 Mac 上的 Cmd+C) 停止終端機上執行的
logcat程序。 - 這項工作階段的記錄會儲存到名為
_logs.txt的檔案。
您可以透過各種方式分析這個檔案的資訊，包括搜尋 error、exception 或 crash 等關鍵字。
記錄指令碼
為方便起見，範例應用程式提供相關指令碼，可取得相關記錄並編譯為文字檔。為提供最佳偵錯體驗，請在回報任何錯誤時附上這些記錄，方便 Google 進行根本原因分析。
這些記錄檔位於範例應用程式來源樹狀結構的 scripts 目錄中。
從專案根目錄執行下列步驟：
- 取得行動裝置 ID：
adb devices -lList of devices attached device-id device
- 執行
get_logs.sh指令碼：./scripts/get_logs.sh device-idCleared previous logs from device. Saving version information to home_api_sample_logs_20240605233243.txt... Saving logs to home_api_sample_logs_20240605233243.txt... (Press CTRL+C to stop the script)
- 重現您遇到的問題。
- 按下
CTRL+C即可停止指令碼。
指令碼會產生包含所有相關資訊的記錄檔，並加上時間戳記。如果遇到錯誤，請將這些檔案附加到報告中。
Cast 中樞裝置記錄
你可以使用這個方法查看 Google Nest Hub 的裝置記錄，支援的機型如下：
- Google Home
- Google Nest Audio
- Google Nest Hub
- Google Nest Mini
如要啟用 Cast 中樞裝置，以便擷取本機記錄，請按照下列步驟操作：
- 設定 Android Debug Bridge。
取得中樞的 IP 位址：
- 如果中控螢幕有螢幕：
- 從畫面頂端向下滑動。
- 輕觸「設定」圖示
- 找出裝置 IP 位址：在 Nest Hub (2nd gen) 上，依序前往「裝置資訊」>「技術資訊」>「IP 位址」
- 在手機上開啟 GHA：
- 輕觸裝置，開啟裝置詳細資料頁面
- 輕觸「設定」圖示 ，開啟設定頁面
- 找出裝置 IP 位址：依序前往「裝置資訊」>「技術資訊」>「IP 位址」
- 如果中控螢幕有螢幕：
在與裝置連上相同 Wi-Fi 網路的電腦上：
adb connect ip-addressadb logcat如要將記錄提供給他人，請執行失敗的作業，並將輸出內容導向文字檔：
adb logcat -d > platform-logs.txt
自動化動作
邊緣偵測
Google Home 生態系統中的自動化動作具備邊緣偵測功能，這項邏輯會驗證啟動條件是否僅在實際狀態變更時啟動，而非在狀態更新時啟動 (狀態更新只會重複裝置先前的狀態)。
舉例來說，如果開啟燈具是啟動條件，邊緣偵測功能會驗證啟動條件是否只在燈具從關閉變成開啟時啟動，而不是從開啟變成開啟 (沒有變化)。
自動化動作未如預期運作
考量邊緣偵測後，如果自動化作業未如預期運作，請採取下列行動：
檢查每部裝置，確認裝置是否能獨立運作，不受自動化動作影響。
查看自動化動作的自動化圖表，並與自動化 DSL 比較，找出您可能做出的任何錯誤假設。
在執行自動化動作期間，透過 Google Home 應用程式觀察裝置狀態。
確認自動化動作參照的所有裝置都位於預期結構中。刪除自動化功能所依附的裝置可能會導致非預期的後果。請參閱「刪除裝置對自動化動作的影響」。
自動化動作在不該執行的時間執行
如果自動化動作在不應執行的時間執行，請檢查啟動條件。 您可能需要新增額外邏輯，確保狀態變更只會擷取一次，且自動化動作只會觸發一次。
自動化動作無法編譯
請確認應用程式包含所有必要匯入項目，包括對應不同節點類型的每個類別，以及您參照的特徵。
自動化作業建立失敗，驗證未通過
如果自動化建立作業未通過驗證，系統會顯示警告或錯誤訊息，說明問題。詳情請參閱ValidationIssueType 參考資料。
清單函式會擲回例外狀況
呼叫 Automation API List 函式時，讀取處理常式可能會因缺少 API 功能而擲回例外狀況。如要解決這個問題，請刪除受影響的自動化程序。
步驟如下：
- 確認已安裝
adb。請參閱安裝 adb。 叫用下列項目，從 Android 記錄中擷取自動化作業的 ID：
adb logcat -s GhpNative記錄範例：
adb logcat -s GhpNative level:debug | grep -A 10 -B 10 AutomationManagerTrait\.ListResponse INTERACTION RESPONSE -> SendCommandsResponse: 1 { 1: "automation@global" 3 { 1: "home.internal.traits.automation.AutomationManagerTrait.ListResponse" 2: 5 { 1: "type.googleapis.com/home.internal.traits.automation.AutomationManagerTrait.ListResponse" 1 { 1: "1111-2222-3333-44444-55555" // Automation ID to delete 2: "structure@2222-3333-4444-5555-6666" ...如要刪除多個自動化 ID，可以使用終端機分頁程式控制輸出內容：
adb logcat -s GhpNative level:debug | less使用自動化動作的 ID 刪除自動化動作：
structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))
如果特徵未註冊，Discovery API 會記錄警告
如果 Discovery API 記錄 Trait not found 的警告，表示 API 嘗試將特徵用於 Discovery 候選項目，但由於特徵未在初始化期間註冊，因此不會成功。例如：
09-03 17:45:20.578 10646 10646 W AutomationSdk: trait_id: "home.matter.6006.clusters.fc43" and Exception occurred com.google.home.HomeException: 18: Trait not found: home.matter.6006.clusters.fc43
09-03 17:45:20.578 10646 10646 W AutomationSdk: While converting candidate: # com.google.home.platform.traits.AutomationCandidateNode@76f0b582
特徵 ID 為 home.matter.6006.clusters.fc43，對應至 RelativeHumidityControl。如要根據 ID 判斷特徵名稱，請參閱特徵索引。
在這個範例中，RelativeHumidityControl 需要在應用程式初始化期間註冊。請參閱「註冊特徵」一文，將特徵新增至登錄檔。
OAuth
如果您有現有的 OAuth 用戶端
如果您已為發布的應用程式建立經過驗證的 OAuth 用戶端，可以使用現有的 OAuth 用戶端測試 Home API。
Google Home Developer Console，即可測試及使用 Home API。不過，即使您有來自其他整合服務的已驗證 OAuth 用戶端，仍須通過Developer Console註冊核准，才能發布應用程式。
請注意下列事項：
使用現有 OAuth 用戶端時，使用者人數上限為 100 人。如要瞭解如何新增測試使用者，請參閱「設定 OAuth 同意畫面。 除了 OAuth 驗證外，Google Home API 也設下限制，應用程式最多只能向 100 位使用者要求授權。完成 Developer Console 註冊後，這項限制就會解除。
Developer Console 註冊 應在您準備透過 OAuth 限制裝置類型授權，為使用 Home API 更新應用程式做準備時，送交審核。
對於Google Cloud仍待 OAuth 驗證的應用程式，使用者必須等到驗證完成，才能完成 OAuth 流程。嘗試授予權限時會失敗，並顯示下列錯誤：
Access blocked: <Project Name> has not completed the Google verification process.