iOS で Home API を使用してモバイルアプリを作成する

1. はじめに

f154e30306882c74.png

Google Home API とは何ですか?

Google Home API は、デベロッパーが Google Home エコシステムを利用できるようにする一連のライブラリを提供します。Google Home API を使用すると、デベロッパーはスマートホーム デバイスをシームレスにコミッショニングして操作するアプリを構築できます。

3e11583c779a2cec.png

この動画では、作成するモバイルアプリの概要を簡単に説明します。Codelab を進めながら、動画をご覧ください。

Google Home API のコンポーネント

Google Home API は、次の要素で構成されています。

  • Device API と Structure API: ユーザーの家を操作します。アプリは、これらの API を使用して、デバイス、部屋、ストラクチャに関する情報を読み取り(サーモスタットの現在の温度を確認するなど)、デバイスを制御(サーモスタットの設定温度を変更するなど)できます。
  • Commissioning API: 最小限の労力で新しい Matter デバイスをファブリックにコミッショニング(セットアップ)します。
  • Automation API: ユーザーの家で実行されている自動化を作成、削除、クエリします。

前提条件

  • Xcode の最新の安定版。
  • 家に少なくとも 1 つのストラクチャが登録されている Google アカウント。
  • iOS 16.4 以降を搭載し、テスト アカウントが設定された iOS デバイス。
  • プロビジョニング プロファイルを生成するために Apple Developer Program に登録された Apple ID。
  • Google Home API をサポートする Google ハブ。

学習内容

  • Google Home API を使用して iOS アプリを構築する方法と、ベスト プラクティス。
  • Device API と Structure API を使用してスマートホームを表現、制御する方法。
  • Commissioning API を使用して Google Home エコシステムにデバイスを追加する方法。
  • Automation API を使用して基本的な自動化を作成する方法。

2. 家をセットアップする

デバイスを準備する

Google Home Playground には、事前に構築されたさまざまなエミュレートされたスマートホーム デバイスが用意されています。特に、自宅のデバイス数が限られている場合は、Google Home API の可能性を最大限に引き出すために、Google Home Playground を使用することをおすすめします。

手順に沿って Google Home Playground にログインし、Google Home アプリでアカウントのリンクを完了します。完了すると、Google Home アプリの [デバイス] タブにデバイスが表示されます。

c892afce113abe8f.png

3. 設定方法

サンプルアプリのコードを取得する

まず、GitHub からソースコードのクローンを作成します。

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

サンプル ディレクトリには、この Codelab 用の start と finished の 2 つのブランチが含まれています。

  • start: このプロジェクトのスターター コード。これに変更を加えて Codelab を完了します。
  • finished: この Codelab の完成したコード。作業のチェックに使用します。

「start」コードを確認する

クローンを作成したリポジトリの start ブランチに切り替えて、この Codelab を開始します。

git checkout start

このブランチには、プロジェクトのスターター コードが含まれています。この Codelab では、このコードを変更して、すべての機能を実装します。Codelab のサンプルアプリは、Google Home API iOS SDK とやり取りするための Swift で構築された基本的な構造を提供します。start プロジェクトの主なコンポーネントは次のとおりです。

  • Main Entry (GoogleHomeAPISampleIOSApp): GoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swift にある、メインのアプリ エントリ ポイント。SDK を構成して初期化し、メインのユーザー インターフェースを設定します。
  • Core Views (View/):
    • MainView.swift: 起動後のルートビュー。メインの NavigationView が含まれます。アクティブな Google Home の家のストラクチャの選択を処理し、対応する StructureView を表示します。
    • StructureView.swift: 現在選択されているストラクチャのコンテンツが表示されます。タブを使用して、[デバイス] のグリッドと [自動化] リストを切り替えることができます。また、部屋やデバイスを追加するためのメニューも表示されます。
    • DeviceView.swift: StructureView グリッド内の 1 つのデバイスのインタラクティブ タイルを表します。
    • AutomationsView.swift: ストラクチャの既存の自動化のリストを表示し、自動化の詳細を作成または表示するためのナビゲーションを提供します。
  • ViewModels (ViewModel/): これらのクラスは、ビューの状態とロジックを管理します。
    • AccountViewModel.swift: Home オブジェクトへの接続を処理し、認証状態を管理します。
    • MainViewModel.swift: 使用可能な Structure オブジェクトのリストを管理し、選択されたストラクチャを追跡します。
    • StructureViewModel.swift: 選択したストラクチャ内の部屋と DeviceControl オブジェクトの表示を管理します。
    • AutomationList.swift、AutomationViewModel.swift など: 自動化の取得、表示、作成、管理を処理します。
  • Device Controls (ViewModel/Device/):
    • DeviceControl.swift: UI で制御可能なデバイスを表す基本クラス。
    • 特定のサブクラス(LightControl.swift、FanControl.swift、OnOffPlugInUnitControl.swift など): 特性に基づいて、さまざまなデバイスタイプの UI ロジック、デバイス制御、状態マッピングを実装します。
    • DeviceControlFactory.swift: 指定された HomeDevice に適した DeviceControl サブクラスを作成します。
  • Commissioning (Commissioning/):
    • CommissioningManager.swift: Matter デバイスのコミッショニング フローを管理するロジックが含まれています。
  • Utilities & UX (Utils/, UX/, Storage/): UI 要素(色、サイズ)、エラー処理、データ ストレージ(SelectedStructureStorage.swift)、その他のユーティリティのヘルパーコードが含まれています。

この Codelab では、start プロジェクト内に TODO などのコメントや、コメントアウトされたコードブロック、アラートが表示されます。これらのコメントは、必要な機能を実装するためにコードを追加またはコメント化解除するセクションを示しています。

Apple デプロイ構成ファイルを作成する

App Attest を構成するには、Apple デプロイ構成ファイルの作成手順に沿って操作します。設定後、アプリはシミュレータではなく、実機にのみデプロイできます。

認証を設定する

OAuth クライアント ID を取得して Google Home API を有効にするには、まず Google Cloud にログインし、新しいプロジェクトを作成するか、既存のプロジェクトを選択します。次に、OAuth クライアント ID を生成して Google Home API を有効にする手順に沿って、アカウントを許可リストに追加します。

SDK を設定する

Google Home API iOS SDK を入手し、SDK を設定するに記載されている設定手順に沿って設定します。HOME_API_TODO_ADD_APP_GROUP は、独自のアプリグループに置き換えてください。

プロジェクトをビルドして実行する

start ブランチでプロジェクトをビルドして実行すると、TODO ダイアログと「ログインが必要です」と表示された画面が表示されます。Google Home API の操作は、以降のセクションで実装します。

bd56b7080037e38a.png 9c0f08a3f4197a77.png

注: 修正が必要なコードを見つけるには、ダイアログに表示されるテキストをプロジェクト内で検索します。たとえば、「TODO: initialize Home」を検索します。

4. 初期化

Home を初期化する

iOS 向け Google Home API を使用する前に、アプリで Home を初期化する必要があります。Home は SDK の最上位エントリであり、ユーザーのストラクチャ内のすべてのエンティティへのアクセスを提供します。特定のタイプのすべてのエンティティをリクエストすると、API は Query オブジェクトを返します。このオブジェクトを使用すると、結果の受信方法を選択できます。GoogleHomeAPISampleIOS/Accounts/AccountViewModel.swift で、connect() のコメントとアラートを削除して、ホームの初期化を実装します。

  /// TODO: initialize Home
  /// Remove comments to initialize Home and handling permission.
  private func connect() {
    Task {
      do {
        self.home = try await Home.connect()
      } catch {
        Logger().error("Auth error: \(error).")
      }
    }
  }

Google Home API を使用する権限

アプリを実行すると、同意画面が表示されます。Google Home のストラクチャを選択し、Google Cloud プロジェクトの許可リストに登録されているアカウントを選択します。

47310f458c0094d9.png 4a571dbd9979a88c.png e29c75891a3a67af.png

5. デバイスとストラクチャ

部屋とデバイスを取得する

GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift で、getRoomsAndDevices() のコメントとアラートを削除し、選択したストラクチャ内の部屋とデバイスをそれぞれ home.rooms() と home.devices() で取得します。

  /// TODO: get rooms and devices
  /// Remove comments to get the rooms and devices from home entry
  private func getRoomsAndDevices(){
    self.home.rooms().batched()
      .combineLatest(self.home.devices().batched())
      .receive(on: DispatchQueue.main)
      .catch { error in
        Logger().error("Failed to load rooms and devices: \(error)")
        return Just((Set<Room>(), Set<HomeDevice>()))
      }
      .map { [weak self] rooms, devices in
        guard let self = self else { return [] }
        self.hasLoaded = true
        return self.process(rooms: rooms, devices: devices)
      }
      /// receive from .map and .assign() to publisher entries
      .assign(to: &self.$entries)
  }

process() 関数は、まずデバイスが同じ部屋にあることを確認してから、DeviceControl と DeviceControlFactory を使用してデバイスを HomeDevices として操作します。

4c677c4c294e67ca.png

注: デバイスが DeviceControlFactory に記載されていない場合は、「サポート対象外」と表示されます。サポートされているデバイスの詳細については、iOS でサポートされているデバイスの種類のページをご覧ください。

デバイスを操作する

デバイスをタップまたはスライドしたとき、プラグ outlet1 は最初は無効になっています。操作を有効にするには、GoogleHomeAPISampleIOS/ViewModel/Device/OnOffPlugInUnitControl.swift を見つけて、primaryAction() 関数内のコメントとアラートを削除します。

  /// TODO: primary action of OnOffPlug
  /// Toggles the plug; usually provided as the `action` callback on a Button.
  public override func primaryAction() {
    self.updateTileInfo(isBusy: true)
    Task { @MainActor [weak self] in
      guard
        let self = self,
        let onOffPluginUnitDeviceType = self.onOffPluginUnitDeviceType,
        let onOffTrait = onOffPluginUnitDeviceType.matterTraits.onOffTrait
      else { return }

      do {
        try await onOffTrait.toggle()
      } catch {
        Logger().error("Failed to to toggle OnOffPluginUnit on/off trait: \(error)")
        self.updateTileInfo(isBusy: false)
      }
    }
  }

OnOffPlugInUnitControl クラス内にある primaryAction() 関数は、スマートプラグまたは OnOffPluginUnitDeviceType で表されるデバイスの電源状態を切り替えます。

デバイス コントロールのその他の例については、GoogleHomeAPISampleIOS/ViewModel/Device をご覧ください。

新しい部屋を作成する

Structure API を使用すると、部屋の作成と削除、部屋間でのデバイスの移動を行うことができます。

GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift で、addRoom() のコメントとアラートを削除します。

  /// TODO: add room
  /// Add a new room in a given structure.
  func addRoom(name: String, structure: Structure) {
    Task {
      do {
        // The view will be updated with the values from the devices publisher.
        _ = try await structure.createRoom(name: name)
      } catch {
        Logger().error("Failed to create room: \(error)")
      }
    }
  }

structure.createRoom() で新しい部屋を作成するには、左上にある + アイコン > [部屋を追加] を選択します。新しい部屋名を入力し、[部屋を作成] をクリックします。数秒後に新しい部屋が表示されます。

b122ae6642b7da1c.png a45f785e1d51938e.png 7753b56cbdcff8d6.png

デバイスを別の部屋に移動する

GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift で、moveDevice() のコメントとアラートを削除します。

  /// TODO: move device
  /// Move a device into a different room.
  func moveDevice(device deviceID: String, to roomID: String, structure: Structure) {
    Task {
      do {
        _ = try await structure.move(device: deviceID, to: roomID)
      } catch {
        Logger().error("Failed to move to room: \(error)")
      }
    }
  }

structure.move() でデバイスを移動するには、デバイスを長押しして [別の部屋に移動] を選択し、新しい部屋を選択します。

f9627592af44163d.png fd126fabb454f2bf.png 813e1e23e50cd9f6.png

空の部屋を削除する

GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift で、removeRoom() のコメントとアラートを削除します。

  /// TODO: delete room
  /// Delete an empty room in a given structure.
  func removeRoom(id: String, structure: Structure) {
    Task {
      do {
        // The view will be updated with the values from the devices publisher.
        _ = try await structure.deleteRoom(id: id)
      } catch {
        Logger().error("Failed to remove room: \(error)")
      }
    }
  }

structure.deleteRoom() を使用して空の部屋を削除するには、部屋名の右側にあるゴミ箱アイコンをクリックして、操作を確定します。削除できるのは空の部屋のみです。

4f129262ad67f564.png

注: デバイスを元に戻すと、空の部屋が作成されます。

6. コミッショニング

注: このセクションの手順には、Google ハブと Matter デバイスが必要です。ストラクチャ内の Google ハブがオンラインで、アクセス可能であることを確認します。Matter デバイスをお持ちでない場合は、代わりに Matter 仮想デバイス アプリを使用してみてください。

Matter デバイスを追加する

Commissioning API を使用すると、アプリからユーザーの家と Google アカウントに新しい Matter デバイスを追加できます。これにより、アプリ内で直接シームレス連携のセットアップ エクスペリエンスを提供できます。

GoogleHomeAPISampleIOS/Commissioning/CommissioningManager.swift で、addMatterDevice() のコメントとアラートを削除します。

  /// TODO: add Matter Device
  /// Starts the Matter device commissioning flow to add the device to the user's home.
  /// - Parameters:
  ///   - structure: The structure to add the device to.
  ///   - add3PFabricFirst: Whether to add the device to a third party fabric first.
  public func addMatterDevice(to structure: Structure, add3PFabricFirst: Bool) {
    self.isCommissioning = true

    /// pass if it's 1p or 3p commissioning
    let userDefaults = UserDefaults(
      suiteName: CommissioningManager.appGroup)
    userDefaults?.set(
    add3PFabricFirst, forKey: CommissioningUserDefaultsKeys.shouldPerform3PFabricCommissioning)

    Task {
      do {
        try await structure.prepareForMatterCommissioning()
      } catch {
        Logger().error("Failed to prepare for Matter Commissioning: \(error).")
        self.isCommissioning = false
        return
      }

      // Prepare the Matter request by providing the ecosystem name and home to be added to.
      let topology = MatterAddDeviceRequest.Topology(
        ecosystemName: "Google Home",
        homes: [MatterAddDeviceRequest.Home(displayName: structure.name)]
      )
      let request = MatterAddDeviceRequest(topology: topology)

      do {
        Logger().info("Starting MatterAddDeviceRequest.")
        try await request.perform()
        Logger().info("Completed MatterAddDeviceRequest.")
        let commissionedDeviceIDs = try structure.completeMatterCommissioning()
        Logger().info("Commissioned device IDs: \(commissionedDeviceIDs).")
      } catch let error {
        structure.cancelMatterCommissioning()
        Logger().error("Failed to complete MatterAddDeviceRequest: \(error).")
      }

      self.isCommissioning = false
    }
  }

structure.prepareForMatterCommissioning() で新しい部屋を作成するには、左上の + アイコン > [Add Device to Google Fabric] を選択します。MatterAddDeviceRequest を使用して、Matter デバイスを部屋に追加します。部屋とデバイス名を選択すると、デバイスが [デバイス] 画面に表示されます。

adf6cbb531787aaf.png f002bd6320bc480d.png

7. 自動化

ストラクチャ内のすべての自動化を表示する

下部のナビゲーション バーにある [自動化] をタップします。structure.listAutomations() を使用して、ストラクチャ内のすべての自動化を一覧表示します。

cc6d50f72f812c24.png

注: スマートホームが設定されていない場合は、「自動化を追加して開始」というメッセージが表示されます。

自動化の作成

Device API と Structure API、新しいデバイスの追加について理解したところで、Automation API を使用して新しい自動化を作成しましょう。

GoogleHomeAPISampleIOS/ViewModel/Automation/AutomationsRepository.swift で、lightAutomation() のコメント、アラート、空の自動化を削除します。

  /// TODO: create automation
  /// - Parameter devices: devices in current selected structure
  /// - Returns: the automation object to be created
  /// This automation will turn off the light after 5 seconds.
  public func lightAutomation(devices: Set<HomeDevice>) async throws -> any DraftAutomation {
    let light = devices.first { $0.name == "light2" }
    
    guard let light else {
      Logger().error("Unable to find light device with name light2")
      throw HomeError.notFound("No devices support OnOffLightDeviceType")
    }
    
    return automation(
      name: "Turn off light after 5 seconds",
      description:
        """
        Turns off light2 after it has been on for 5 seconds.
        """
    ) {
      let onOffStarter = starter(light, OnOffLightDeviceType.self, OnOffTrait.self)
      onOffStarter
      condition {
        onOffStarter.onOff.equals(true)
      }
      delay(for: Duration.seconds(5))
      action(light, OnOffLightDeviceType.self) {
        OnOffTrait.off()
      }
    }
  }

ライトがオンになってから 5 秒後にオフにする自動化を作成するには、自動化ビューに移動して [+ 追加] ボタンをクリックします。[5 秒後にライトを消す] を選択します。starter、condition、action などの自動化の詳細が表示されます。[保存] をクリックして、structure.createAutomation() による自動化を作成します。

21c1f8ea2a29134b.png 4bd36f6ed9c5f6e9.png

注: 利用できる自動化は、家にあるデバイスによって異なります。利用可能な自動化が表示されない場合は、照明デバイスの名前を「light2」に変更してみてください。

[デバイス] タブに戻り、「light2」という名前のライトをオンにします。5 秒後に自動的にオフになります。

自動化のコンポーネントは次のとおりです。

  • 開始条件: 自動化を開始するイベントです。この例では、OnOffTrait に変更があると自動化が開始されます。
  • 条件: 開始条件デバイスが特定の要件を満たしているかどうかを確認します。この場合、ライトが点灯していると自動化が実行されます。
  • アクション: 実行する自動化です。ただし、開始条件が要件を満たしている場合にのみ実行されます。条件が満たされると、ライトが消灯します。

その他の例については、自動化の例のページをご覧ください。

自動化を削除する

structure.deleteAutomation() メソッドは、既存の自動化を左にスワイプしてゴミ箱アイコンをタップし、ストラクチャから削除するときに呼び出されます。

dc678cd9e16f89a5.png

8. 完了

おめでとうございます!iOS 向け Google Home API を使用して、基本的なスマートホーム アプリを作成しました。

達成したこと:

  • 初期化: Home.connect() を使用してアプリを Google Home エコシステムに接続しました。
  • 権限: 家のデータにアクセスするためのユーザー認証と認可を処理します。
  • デバイスとストラクチャ: home.rooms() と home.devices() を使用して、部屋とデバイスを取得して表示しました。
  • デバイス制御: トレイトのコマンドを呼び出して OnOffPluginUnitDeviceType の状態を切り替えるなど、デバイスの操作を実装しました。
  • ストラクチャ管理: 新しい部屋の作成(structure.createRoom())、部屋間のデバイスの移動(structure.move())、空の部屋の削除(structure.deleteRoom())の機能を追加しました。
  • コミッショニング: SDK のコミッショニング フローを統合して、新しい Matter デバイスを追加しました(MatterAddDeviceRequest)。
  • 自動化: ストラクチャ内の自動化を一覧表示、作成(structure.createAutomation())、削除(structure.deleteAutomation())する方法について説明しました。

これで、Google Home API を活用して iOS で充実したスマートホーム コントロール エクスペリエンスを構築する方法について、基本的な知識を習得できました。

次のステップ:

  • サンプルアプリで提供されている他のデバイスタイプ(照明、ファン、ブラインドなど)の操作を試します。
  • さまざまなデバイスで利用できる特性とコマンドの詳細を確認する。
  • さまざまな開始条件、条件、アクションを使用して、より複雑な自動化を作成してみましょう。
  • より高度な機能と詳細については、Google Home API のドキュメントをご覧ください。

お疲れさまでした。