建構 iOS 範例應用程式

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

必要條件

確認您符合使用 iOS 版 Home API 的基本需求。

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

下載 Xcode

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

1. Google 帳戶。
2. 已註冊 Apple 開發人員計畫的 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 功能。因此無法部署至模擬器裝置。您必須使用「應用程式認證」權利建立佈建設定檔。

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

詳情請參閱 Apple 的建立開發布建描述檔，瞭解佈建描述檔。

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

1. 為應用程式建立應用程式群組 ID，以便與 MatterExtension 通訊。
   1. 登入 Apple 開發人員入口網站。
   2. 新增應用程式群組 ID。舉例來說，格式可能為 group.com.company.commissioning。
2. 向開發人員帳戶註冊測試裝置。

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

   1. 決定應用程式的應用程式套件組合 ID。這個 ID 應是專屬且具描述性。舉例來說，格式可能為 com.company.HomeApiSample。本節的其餘部分都會使用這個 ID。
   2. 註冊應用程式 ID。 系統提示時，請新增「App Attest」和「App Groups」功能。

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

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

      • 如果尚未建立，請參閱建立開發人員 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 專案設定同意畫面，系統會顯示「設定同意畫面」按鈕。在這種情況下，請按照下列程序設定同意畫面。如果已設定 OAuth 同意畫面，且發布狀態為「測試中」，請務必將要使用的測試帳戶新增至「測試使用者」群組。如果沒有看到提示訊息，請繼續執行下一步。

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

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

   

   

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

啟用 Home API

啟用 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

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

建構應用程式

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

立即登入！

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

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

   

   

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 同意聲明」一節)、與雲端專案對應的 Cloud Project Number，以及 OAuth 註冊程序中使用的開發人員帳戶的 Apple 開發人員團隊 ID，填入 GIDClientID 和 GIDTeamID。

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

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

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

    

    

    1. 前往 GoogleHomeAPISampleIOS 專案 > GoogleHomeAPISampleIOS 目標。
    2. 依序點選「簽署和功能」>「+ 功能」。
    3. 選取「應用程式群組」功能。
    4. 按一下「應用程式群組」下方的「+」圖示，然後新增您在 Apple 開發人員入口網站中新增的應用程式群組 ID。
    5. 針對 MatterAddDeviceExtension 目標重複上述步驟，將其新增至 App Groups。

14. 更新套件 ID

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

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

    1. 應用程式必須設定 SDK 執行個體，才能使用應用程式群組 ID 進行裝置委派等功能。更新應用程式，使用在 Apple Developer Portal 中註冊的應用程式群組 ID，方法是搜尋字串 HOME_API_TODO_ADD_APP_GROUP，然後將每個執行個體替換為該字串。

    這些設定是在下列檔案中進行：

    • 初始化 SDK 時。GoogleHomeAPISampleIOS.swift
    • RequestHandler.swift
    • CommissioningManager.swift