Home API Android 範例應用程式

範例應用程式展示了 Android 版 Google Home API 的基本功能。

必要條件

如要建構、安裝及測試應用程式，您必須符合幾項必要條件：

  • Android Studio 2024.2.1 版 (「Ladybug」) 以上版本。請注意，如果版本早於此版本，可能無法與 Home API SDK 正常搭配運作。

    下載 Android Studio

  • Android 偵錯工具 (adb)。

    安裝 adb。

    方法是使用 SDK Manager。

如要測試 Home API，您需要：

  • 搭載 Android 10 以上版本的 Android 裝置，並已設定要用於開發的 Google 帳戶。請確認已安裝最新版本的 Android Studio，並使用這個開發人員帳戶登入。
  • Wi-Fi 網路。
  • 如要存取及控制 Matter 裝置，你還需要支援 Home API 的 Google 中樞裝置。詳情請參閱「Android 連線能力 」。

  • 住家中至少有一部支援的裝置。如果這部裝置 (或任何其他要測試的裝置) 使用 Thread，中樞也必須是 Thread Border Router (TBR)。Android 範例應用程式支援下列裝置類型和特徵：

    • 色溫燈 (開關、亮度)
    • 接觸感應器 (布林值狀態)
    • 可調光燈具 (開關、亮度)
    • 門鎖
    • 擴充彩色燈 (開關、亮度)
    • 一般切換
    • Google 邊界路由器
    • Google 相機
    • Google Doorbell
    • 活動情形感應器 (在宅感應)
    • 開關燈 (開和關、亮度)
    • 電燈開關
    • 開/關外掛式裝置 (開和關)
    • 開關感應器

下載原始碼

您可以在 GitHub 找到範例應用程式的原始碼。

前往要儲存專案的位置，然後複製專案：

git clone https://github.com/google-home/google-home-api-sample-app-android.git

設定 SDK

這個公開測試版中的 Android Home API 尚未納入 Google 提供的標準開發程式庫。如要使用 Home API 開發 Android 應用程式，您必須在本機下載並託管程式庫。

如要下載 Home API Android SDK，請先登入 Google Home 開發人員。

立即登入！

建構應用程式

  1. 開啟 Android Studio，然後開啟複製到本機電腦的 google-home-api-sample-app-android 專案資料夾。

  2. 首次設定時，Android Studio 最多可能需要 10 分鐘，才能下載所有專案依附元件並完成 Gradle 建構作業。

  3. 使用 USB 傳輸線將電腦連接至實體 Android 手機，並在開發人員選項中啟用 ADB。確認 Android Studio 可透過 ADB 連線至 Android 手機。

  4. 將範例應用程式的套件名稱變更為尚未註冊的新名稱，例如以貴機構名稱為基礎的名稱：

    1. 開啟專案。
    2. 展開來源階層。
    3. 選取要變更的套件部分，也就是 com.example。
    4. 在套件上按一下滑鼠右鍵，然後依序選取「Refactor」 >「Rename...」 「Refactor」>「Rename」選單
    5. 輸入新名稱，然後按一下「Refactor」。
    6. 編輯 build.gradle.kts 檔案，將 android namespace 和 applicationId 變更為新的套件名稱。

  5. 在 HomeModule.kt 中設定 OAuth 範圍。根據預設，範例應用程式原始碼會使用 https://www.googleapis.com/auth/home.platform.v2 範圍。範例應用程式中的許多功能都受到 home.platform.v2 範圍限制，必須經過合作夥伴核准才能存取。如要使用標準 https://www.googleapis.com/auth/home.platform.selected.devices 範圍執行範例應用程式，請開啟 HomeModule.kt，並將 HomeConfig 中的 homePlatformScope 變更為 HOME_PLATFORM_SCOPE_VERSION_1：

    val homeConfig = HomeConfig(
  coroutineContext = Dispatchers.IO,
  factoryRegistryProvider = {
    FactoryConstants.factoryRegistryAllTraitsAllTypes
  },
  homePlatformScope =
    HomeConfig.HomePlatformScope.HOME_PLATFORM_SCOPE_VERSION_1
)

此外，請將 HomeClientProvider.kt 中 switchAccount() 的 homePlatformScope 更新為 HOME_PLATFORM_SCOPE_VERSION_1。否則，選取個人資料圖示切換帳戶時，應用程式會還原為 HOME_PLATFORM_SCOPE_VERSION_2。

  1. 下載完所有必要程式庫，且 Gradle 同步處理完成後，請按一下「Run」按鈕，建構並執行應用程式。應用程式在手機上成功執行後，您會看到範例應用程式主頁面。

建立簽署憑證

在 Android Studio 中執行或偵錯應用程式時，系統會自動產生用於開發和偵錯的偵錯憑證。如需完整說明，請參閱「Android Studio：簽署偵錯版本」。

  1. 在 Android Studio 中執行應用程式，產生偵錯應用程式簽署憑證。在 Android Studio 中執行或偵錯應用程式時，Android Studio 會自動產生用於開發和偵錯的應用程式簽署憑證。如需完整說明，請參閱「Android Studio：簽署偵錯版本」。

    將行動裝置連接到本機電腦。 Android Studio 會依型號列出已連結裝置。從清單中選取裝置，然後按一下「Run project」。這項操作會在行動裝置上建構及安裝範例應用程式。

    如需詳細操作說明，請參閱 Android 開發人員網站上的「在硬體裝置上執行應用程式」一文。

    現在，請停止執行中的應用程式。

  2. 請按照 Google Cloud 控制台說明網站中「管理 OAuth 用戶端 / 應用程式類型 / 原生應用程式 / Android」一節的詳細操作說明，取得偵錯憑證的 SHA-1 指紋。

  1. 在 Google Cloud 控制台中，前往專案選取器資訊主頁，選取要用來建立 OAuth 憑證的專案。
  2. 前往「APIs and Services」(API 和服務) 頁面，然後按一下導覽選單中的「Credentials」(憑證)。

  3. 如果您尚未設定這項 Google Cloud 專案的同意畫面，系統會顯示「Configure consent screen」(設定同意畫面) 按鈕。在這種情況下，請按照下列程序設定同意畫面。否則，請繼續閱讀下一節。

    1. 按一下「設定同意畫面」。系統會顯示「OAuth consent screen」(OAuth 同意畫面) 頁面。
    2. 視用途選取「Internal」(內部) 或「External」(外部)，然後按一下「Create」(建立)。系統會顯示「OAuth 同意畫面」窗格。
    3. 按照畫面上的指示，在「App information」(應用程式資訊) 頁面輸入資訊，然後按一下「Save and continue」(儲存並繼續)。系統會隨即顯示「Scopes」窗格。
    4. 您不需要新增任何範圍，因此請按一下「儲存並繼續」。系統會顯示「Test users」(測試使用者) 窗格。
    5. 依序點選「目標對象」和「+ 新增使用者」按鈕。
    6. 輸入測試使用者的電子郵件地址，然後按一下「儲存」按鈕。
    7. 按一下「儲存並繼續」。系統隨即會顯示「Summary」(摘要) 窗格。
    8. 查看 OAuth 同意畫面資訊，然後按一下「Back to dashboard」(返回資訊主頁)。

如需完整詳細資料，請參閱 Google Cloud 控制台說明網站上的「設定 OAuth 同意畫面」。請務必先新增至少一位測試使用者，再繼續操作。

設定 OAuth 憑證

  1. 請按照「設定 OAuth 2.0」中的操作說明，註冊範例應用程式以使用 OAuth 2.0，並建立 OAuth 憑證。
    1. 指出應用程式類型，即原生/Android 應用程式。
    2. 請按照 Google Cloud 控制台說明網站上的「設定 OAuth 2.0 / 原生應用程式 / Android」一文中的操作說明，將 SHA-1 指紋新增至 OAuth 用戶端。在整個開發過程中，您應從預設的 Android Studio 金鑰產生 SHA-1 金鑰。

執行應用程式

  1. 將行動裝置連上本機電腦，然後再次點選「Run project」，在行動裝置上執行範例應用程式。

安裝完成後，應用程式會以 Home API 範例應用程式的形式，顯示在行動裝置上。