建構 iOS 範例應用程式

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

必要條件

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

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

下載 Xcode

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

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

開發時，您需要符合下列需求的 Mac：

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

建立 Apple 部署設定檔

首先，應用程式必須啟用 App Attest 功能。因此無法部署至模擬器裝置。您必須建立具有 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，並設定「App Groups」功能，新增已註冊的應用程式群組 ID。

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

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

    1. 決定 MatterExtension 的軟體包 ID。這個 ID 應沿用應用程式 ID。例如，格式可能為 com.company.HomeApiSample.MatterExtension。
    2. 註冊應用程式 ID。 看到提示時，新增「App Group」功能。
    3. 編輯新建立的應用程式 ID，並設定「App Groups」功能，新增在先前步驟中建立的已註冊應用程式群組 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. 在導覽選單中，按一下「Credentials」(憑證)。

  4. 如果您尚未設定這項 Google Cloud 專案的同意畫面，系統會顯示「Configure consent screen」(設定同意畫面) 按鈕。在這種情況下，請按照下列程序設定同意畫面。如果 OAuth 同意畫面已設定完成，且發布狀態為「測試中」，請務必將要使用的測試帳戶加入「測試使用者」群組。否則，請繼續下一個步驟。

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

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

    設定 OAuth 畫面

    1. 按一下「建立憑證」按鈕，然後選取「OAuth 用戶端 ID」。
      1. 在「應用程式類型」下方，選取「iOS」。
    2. 輸入軟體包 ID，以及應用程式 ID 和 Apple Developer 團隊 ID。其他欄位為選填，可以留空。
    3. 按一下「CREATE」(建立)，然後記下建立的用戶端 ID，或點選「DOWNLOAD PLIST」(下載 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 新增至專案

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

建構應用程式

如要下載 Home API iOS SDK，請先登入 Google Home Developers。

立即登入！

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

  1. 將下載的 SDK 解壓縮至與專案根目錄相對的 ThirdParty/GoogleHomeSDK 目錄。
  2. 設定開發人員和 OAuth 用戶端 ID：
    1. 在導覽窗格中，找出 GoogleHomeAPISampleIOS 資料夾，然後開啟 Info.plist 檔案進行編輯。

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

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

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

  5. 新增「App Groups」功能。

    新增應用程式群組

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

  6. 更新軟體包 ID

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

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

    1. 應用程式必須設定 SDK 執行個體，才能使用應用程式群組 ID 進行裝置委派等功能。更新應用程式，搜尋 HOME_API_TODO_ADD_APP_GROUP 字串並替換每個例項，以使用在 Apple 開發人員入口網站註冊的應用程式群組 ID。

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

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

  8. 在 GoogleHomeAPISampleIOS.swift 中設定 OAuth 範圍。根據預設，範例應用程式原始碼會使用 https://www.googleapis.com/auth/home.platform.v2 範圍。範例應用程式中的許多功能都受到 home.platform.v2 範圍限制，需要合作夥伴核准才能存取。如要使用標準 https://www.googleapis.com/auth/home.platform.selected.devices 範圍執行範例應用程式，請開啟 GoogleHomeAPISampleIOS.swift，並將 Home.configure 中的 homePlatformOAuthScope 變更為 HomePlatformOAuthScope.v1：

    Home.configure {
  $0.sharedAppGroup = "HOME_API_TODO_ADD_APP_GROUP"
  $0.homePlatformOAuthScope = HomePlatformOAuthScope.v1
  ...
}