建構 iOS 範例應用程式

這個 iOS 應用程式範例使用 Google Home API。請參閱本指南，瞭解如何首次建構及執行應用程式。

必要條件

確認您符合使用 iOS 版 Home API 的最低需求。

如要建構及安裝範例應用程式，您需要使用安裝 Xcode 15.3 以上版本的電腦。

下載 Xcode

如要測試應用程式，您需要：

  1. 在 Home APIs EAP 中註冊的 Google 帳戶，用於測試帳戶。
  2. 已註冊 Apple Developer Program 的 Apple ID，以產生實體裝置設定檔。如果尚未建立，註冊程序會產生額外費用，且可能需要最多 48 小時才能完成。
  3. 搭載 iOS 16.4 以上版本的 iOS 裝置 (不是模擬器)，並已設定測試帳戶。
  4. Wi-Fi 網路。
  5. 支援 Home API 的 Google 中樞裝置。
  6. 如果裝置需要 Thread，但中樞不支援，則需要 Thread 邊界路由器。
  7. 至少一個支援的裝置類型。

如要進行開發，您需要 Mac 且符合下列需求條件：

  • macOS Sonoma 以上版本
  • Xcode 15.3 以上版本

建立 Apple 部署設定檔

首先，應用程式必須啟用 App Attest 功能。因此無法部署至模擬器裝置。您必須建立含有 App Attest 授權的佈建設定檔。

其次，您必須啟用應用程式群組，才能在應用程式和 MatterExtension 之間進行通訊。您必須註冊應用程式群組 ID。

詳情請參閱 Apple 的建立開發人員建構設定檔一文，瞭解如何建立建構設定檔。

以下列出部署應用程式所需的基本步驟：

  1. 建立應用程式群組 ID，讓應用程式與 MatterExtension 通訊。
    1. 登入 Apple Developer Portal。
    2. 新增應用程式群組 ID。例如，格式可以是 group.com.company.commissioning。
  2. 將測試裝置註冊至開發人員帳戶。

  3. 為應用程式目標建立設定檔。

    1. 決定應用程式的應用程式套件 ID。此 ID 應具備唯一性且具描述性。例如，格式可以是 com.company.HomeApiSample。這個 ID 會在本節的其餘部分中使用。
    2. 註冊應用程式 ID。畫面出現提示時，請新增「應用程式認證」和「應用程式群組」功能。

    3. 編輯新建立的應用程式 ID，並設定「應用程式群組」功能，以便新增已註冊的應用程式群組 ID。

    4. 為應用程式開發作業建立開發布建設定檔。將其與新建立的應用程式 ID 和所選測試裝置建立關聯。請確認您有用來簽署應用程式的開發人員憑證。

  4. 為 MatterExtension 目標建立設定檔。

    1. 決定 MatterExtension 的應用程式軟體包 ID。這個 ID 應繼承自應用程式 ID。例如，格式可以是 com.company.HomeApiSample.MatterExtension。
    2. 註冊應用程式 ID。系統提示時，請新增「應用程式群組」功能。
    3. 編輯新建立的應用程式 ID，並設定「應用程式群組」功能，以便新增先前步驟中建立的已註冊應用程式群組 ID。
    4. 為 MatterExtension建立開發布建設定檔。

產生 OAuth 用戶端 ID 並啟用 Home API

您的應用程式需要 OAuth 用戶端 ID，才能向 Google 的驗證後端識別自身。針對 iOS 和應用程式，必須將 OAuth 用戶端 ID 應用程式類型設為 iOS。應用程式也會呼叫 Home API。如要啟用這項功能，必須在 Google Cloud 專案中啟用 API。

產生 OAuth 用戶端 ID

  1. 在 Google Cloud 控制台中前往專案選取器資訊主頁，然後選取要用來建立 OAuth 憑證的專案。
  2. 前往「API 和服務」頁面，方法是按一下左上方的「選單按鈕」>「查看所有產品」>「API 和服務」。
  3. 在導覽選單中，按一下「憑證」。

  4. 如果您尚未為這個 Google Cloud 專案設定同意畫面，系統會顯示「Configure consent screen」按鈕。在這種情況下，請按照下列程序設定同意畫面。如果您已設定 OAuth 同意畫面，且發布狀態為「測試」，請務必將要使用的測試帳戶新增至「測試使用者」群組。如果沒有看到提示訊息，請繼續執行下一步。

    1. 視用途而定，選取「內部」或「外部」，然後按一下「建立」。畫面上會顯示 OAuth 同意畫面窗格。
    2. 按照畫面上的指示，在應用程式資訊頁面中輸入資訊，然後按一下「儲存並繼續」。畫面上會顯示「Scopes」窗格。
    3. 您不需要新增任何範圍，因此請按一下「儲存並繼續」。系統會顯示「Test users」窗格。
    4. 如果您選擇建立內部同意畫面，就必須新增使用者，以便測試應用程式的存取權。請按一下「新增使用者」。「新增使用者」窗格隨即顯示。測試使用者有權在應用程式中授予權限。在空白欄位中新增一或多個 Google 帳戶電子郵件地址，然後按一下「新增」。
    5. 按一下「儲存並繼續」。系統會顯示「Summary」窗格。
    6. 查看 OAuth 同意畫面資訊，然後點選「返回資訊主頁」。

  5. 在左側選單面板中，按一下「憑證」建立 OAuth 用戶端 ID。

    設定 OAuth 畫面

    1. 按一下「建立憑證」按鈕，然後選取「OAuth 用戶端 ID」。
      1. 在「application type」下方，選取「iOS」。
    2. 輸入包含應用程式 ID 的 軟體包 ID，以及 Apple 開發人員 團隊 ID。其他欄位為選用欄位，可留空。
    3. 按一下「CREATE」，並記下已建立的「Client ID」或「DOWNLOAD PLIST」。這會在稍後用於啟用權限流程功能。詳情請參閱「建立授權憑證」一節。

啟用 Home API

啟用 Google Home API 存取權。

  1. 在「API 和服務」分頁中，按一下「已啟用的 API 和服務」。
  2. 按一下頁面頂端的「啟用 API 和服務」。
  3. 搜尋並選取 HOME API。
  4. 在「Home API」詳細資料頁面中，按一下「啟用」。

下載原始碼

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

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

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

如要在 Xcode 中載入專案，請依序點選「File」 >「Open」，然後在複製的存放區根目錄中選取 GoogleHomeAPISampleIOS.xcodeproj。

設定 SDK

範例應用程式專案需要一些額外資訊才能建構。這包括在本機新增 SDK Framework 檔案、填入開發人員帳戶 ID 資訊，以及填入 OAuth 客戶端 ID。

建構應用程式

如要下載 Home API iOS SDK，您必須先登入 Google Home 開發人員中心。

立即登入！

為範例應用程式設定 Xcode 專案：

  1. 在 Xcode 導覽窗格中，選取 GoogleHomeAPISampleIOS 檔案來編輯專案設定。

    設定 SDK 範例應用程式

  2. 按一下頂端的「一般」分頁標籤，然後選取左側的目標 GoogleHomeAPISampleIOS。

  3. 向下捲動，直到看到「架構、程式庫和嵌入內容」部分。畫面上應該會列出兩個 Home API 架構。

  4. 在「嵌入」欄中，為 GoogleHomeSDK.xcframework 選取「嵌入並登入」。其他架構 GoogleHomeTypes.xcframework 應設為「Do Not Embed」。

  5. 按一下清單底部的「+」圖示。

  6. 出現提示時，搜尋 SafariServices.framework 並按一下「新增」。確認「嵌入」欄已設為「不嵌入」。

    嵌入及簽署

  7. 按一下「目標」下方的 MatterAddDeviceExtension 圖示，即可編輯目標。

  8. 向下捲動至「架構和程式庫」部分。您應該會看到 GoogleHomeSDK.xcframework 的清單。

  9. 在「內嵌」欄中，選取「不內嵌」。

  10. 設定開發人員和 OAuth 用戶端 ID：

    1. 在導覽窗格中，找出 GoogleHomeAPISampleIOS 資料夾，然後開啟 Info.plist 檔案進行編輯。

  11. 在 Info.plist 檔案中，將 OAuth 用戶端 ID (請參閱「設定 OAuth 同意聲明」一節) 填入 GIDClientID，並將 OAuth 註冊程序中使用的開發人員帳戶的 Apple Developer Team ID 填入 GIDTeamID。

  12. 設定建構系統：

    新增連結器旗標

    1. 在 Xcode 導覽窗格中，選取 GoogleHomeAPISampleIOS 專案檔案，即可編輯專案設定。
    2. 按一下頂端的「Build Settings」分頁標籤，然後選取左側「TARGETS」部分下方的目標 GoogleHomeAPISampleIOS。
    3. 搜尋「Other Linker Flags」，然後新增兩個項目：
      • -lc++
      • -ObjC

  13. 新增應用程式認證功能：

    1. 在 Xcode 導覽窗格中，選取 GoogleHomeAPISampleIOS 專案檔案，即可編輯專案設定。
    2. 按一下頂端的「Signing and Capabilities」分頁標籤，然後選取「TARGETS」部分左側的目標 GoogleHomeAPISampleIOS。
    3. 在「Signing and Capabilities」分頁下方，按一下「+ Capability」，然後搜尋「App Attest」。
    4. 按一下「App Attest」即可新增。如果搜尋結果中沒有這項功能，表示專案可能已新增該功能。

  14. 新增「應用程式群組」功能。

    新增應用程式群組

    1. 依序前往「GoogleHomeAPISampleIOS」專案 >「GoogleHomeAPISampleIOS」目標。
    2. 依序點選「Signing & Capabilities」 >「+ Capability」。
    3. 選取「應用程式群組」功能。
    4. 按一下「應用程式群組」下方的「+」圖示，然後新增您在 Apple Developer Portal 中新增的應用程式群組 ID。
    5. 針對 MatterAddDeviceExtension 目標重複上述步驟，將其加入應用程式群組。

  15. 更新套件 ID

    1. 如要使用開發人員憑證和建構設定檔，在硬體上順利執行及部署範例應用程式，您必須提供專屬的套件 ID。這應該與 OAuth 用戶端憑證相關聯的 ID 相同 (請參閱上方說明)。
    2. 在 Xcode 導覽窗格中，選取 GoogleHomeAPISampleIOS 專案檔案，即可編輯專案設定。
    3. 按一下頂端的「Signing and Capabilities」分頁標籤，然後選取「TARGETS」部分左側的目標 GoogleHomeAPISampleIOS。
    4. 選取「Signing」部分中的「Bundle Identifier」欄位，然後輸入應用程式的專屬 ID。
    5. 選取或安裝與該套件相關的佈建設定檔，並取得必要的授權。
    6. 針對 MatterAddDeviceExtension 目標重複上述步驟，輸入擴充功能的套件 ID，並匯入已註冊的佈建設定檔。

  16. 更新程式碼中已註冊的應用程式群組 ID。

    1. 應用程式必須設定 SDK 例項，才能使用應用程式群組 ID 來執行裝置調試等功能。更新應用程式，以便使用在 Apple Developer Portal 中註冊的應用程式群組 ID，方法是搜尋字串 HOME_API_TODO_ADD_APP_GROUP，並將每個例項都替換為該字串。

    這些設定是在下列檔案中建立：

    • 在 SDK 初始化時，系統會呼叫 GoogleHomeAPISampleIOS.swift。
    • RequestHandler.swift
    • CommissioningManager.swift