1. はじめに
Home API とは何ですか？
Google Home APIs は、デベロッパーが Google Home エコシステムを利用するための一連のライブラリを提供します。Home API を使用すると、スマートホーム デバイスのシームレスなコミッショニングと制御を行うアプリを構築できます。
この動画では、作成するモバイルアプリの簡単なチュートリアルを紹介します。Codelab を行う際は、動画を見ながら進めてください。
Home API のコンポーネント
Home API は次の要素で構成されます。
- デバイスとストラクチャの API: ユーザーの家とやり取りします。アプリはこれらの API を使用して、デバイス、部屋、構造に関する情報を読み取り（たとえば、サーモスタットの現在の温度を確認）、デバイスを制御（たとえば、サーモスタットの設定温度を変更）できます。
- Commissioning API: 最小限の労力で、新しい Matter デバイスをファブリックにコミッショニング（セットアップ）します。
- Automation API: ユーザーの家で実行されている自動化の作成、削除、クエリを行います。
前提条件
- Xcode の最新の安定版。
- 家に少なくとも 1 つのストラクチャがある Google アカウント。
- テスト アカウントでセットアップされた iOS 16.4 以降を搭載した iOS デバイス。
- プロビジョニング プロファイルを生成するための Apple Developer Program に登録されている Apple ID。
- Home API をサポートする Google Hub。
学習内容
- ベスト プラクティスに沿って Home API を使用して iOS アプリをビルドする方法。
- デバイス API と構造 API を使用してスマートホームを表現し、制御する方法。
- Commissioning API を使用してデバイスを Google Home エコシステムに追加する方法。
- Automation API を使用して基本的な自動化を作成する方法。
2. 自宅を設定する
デバイスを準備する
Google Home Playground には、さまざまな事前構築済みのエミュレートされたスマートホーム デバイスが用意されています。特に、家にあるデバイスの数が限られている場合は、Home API の可能性を最大限に引き出すために、このツールを使用することをおすすめします。
手順に沿って Google Home Playground にログインし、Google Home アプリでアカウントのリンクを完了します。完了すると、Google Home アプリの [デバイス] タブにデバイスが表示されるようになります。
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」コードを確認する
この Codelab は、クローンされたリポジトリの start ブランチに切り替えることから始めます。
git checkout start
このブランチには、プロジェクトのスターター コードが含まれています。この Codelab 全体を通して、このコードを変更して完全な機能を実装します。この Codelab のサンプルアプリは、Home APIs 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グリッド内の単一デバイスのインタラクティブ タイルを表します。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 全体を通して、TODO のようなコメントや、start プロジェクト内のコメントアウトされたコードブロックとアラートが表示されます。これらのマークは、提供された手順に沿って必要な機能を実装するためにコードを追加またはコメント解除するセクションを示しています。
Apple デプロイ構成ファイルを作成する
App Attest を構成するには、Apple デプロイ構成ファイルの作成手順に沿って操作します。セットアップ後、アプリはシミュレータではなく、実機にのみデプロイできます。
認証を設定する
OAuth クライアント ID を取得して Home API を有効にするには、まず Google Cloud にログインして、新しいプロジェクトを作成するか、既存のプロジェクトを選択します。次に、手順に沿って OAuth クライアント ID を生成して Home API を有効にし、アカウントを許可リストに追加します。
SDK を設定する
SDK を設定するに記載されている設定手順を参照して、Home APIs iOS SDK を取得し、設定します。HOME_API_TODO_ADD_APP_GROUP は、独自のアプリグループに置き換えてください。
プロジェクトをビルドして実行する
start ブランチでプロジェクトをビルドして実行すると、TODO ダイアログと [Sign in Required]（ログインが必要です）と表示された画面が表示されます。Home API のインタラクションについては、次のセクションで実装します。
注: 変更が必要なコードは、ダイアログに表示されるテキストをプロジェクト内で検索して見つけます。たとえば、「TODO: initialize Home」を検索します。
4. 初期化
ホームを初期化する
iOS 向け 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).")
}
}
}
Home API を使用する権限
アプリを実行すると同意画面が表示されます。Google Home のストラクチャを選択し、Google Cloud プロジェクトの許可リストに登録されているアカウントを選択します。
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 として連携させます。
注: デバイスが 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() で新しいチャットルームを作成するには、左上にある 「+」アイコン > [チャットルームを追加] を選択します。新しいチャットルーム名を入力し、[チャットルームを作成] をクリックします。新しいルームは数秒後に表示されます。
デバイスを別の部屋に移動する
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() でデバイスを移動するには、長押しして [別の部屋に移動] を選択し、新しい部屋を選択します。
空の部屋を削除する
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() を含む空のルームを削除するには、ルーム名の右にあるゴミ箱アイコンをクリックして、操作を確定します。削除できるのは、空のルームのみです。
注: デバイスを移動して、空の部屋を作成します。
6. コミッショニング
注: このセクションでは、Google ハブと Matter デバイスが必要です。構造内の Google ハブがオンラインでアクセス可能であることを確認します。Matter デバイスをお持ちでない場合は、代わりに Matter 仮想デバイスアプリをお試しください。
Matter デバイスを追加する
コミッショニング API を使用すると、アプリで新しい Matter デバイスをユーザーの家と Google アカウントに追加できます。これにより、アプリ内でシームレスな設定エクスペリエンスを提供できます。
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() で新しいルームを作成するには、左上隅に移動して、「+」アイコン > [デバイスを Google Fabric に追加] を選択します。MatterAddDeviceRequest を使用して、Matter デバイスを部屋に追加します。部屋とデバイス名を選択すると、デバイスが [デバイス] 画面に表示されます。
7. 自動化
ストラクチャ内のすべての自動化を表示する
下部のナビゲーション バーにある [自動化] をタップします。structure.listAutomations() を使用して、構造内のすべての自動化を一覧表示します。
注: スマートホームの自動化を設定していない場合は、「自動化を追加して開始」というメッセージが表示されます。
自動化の作成
デバイス API と構造 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() による自動化を作成します。
注: 利用可能な自動化は、ご自宅のデバイスによって異なります。利用可能な自動化が表示されない場合は、照明デバイスの名前を「light2」に変更してみてください。
[デバイス] タブに戻り、「light2」という名前のライトをオンにします。5 秒後に自動的にオフになります。
自動化のコンポーネントは次のとおりです。
- 開始条件: 自動化を開始するイベントです。この例では、
OnOffTraitに変更があると自動化が開始されます。 - 条件: スターター デバイスが特定の要件を満たしているかどうかを確認します。この場合、ライトがオンの場合に自動化が実行されます。
- アクション: 開始条件が要件を満たしている場合にのみ実行する自動化です。条件が満たされると、ライトがオフになります。
その他の例については、自動化の例のページをご覧ください。
自動化を削除する
structure.deleteAutomation() メソッドは、既存の自動化を左にスワイプしてゴミ箱アイコンをタップし、構造から削除するときに呼び出されます。
8. 完了
おめでとうございます！iOS 向け Home API を使用して、基本的なスマートホーム アプリが正常に作成されました。
達成した内容:
- 初期化:
Home.connect()を使用してアプリを Google Home エコシステムに接続しました。 - 権限: スマートホーム データへのアクセスに関するユーザーの認証と認可を処理します。
- デバイスと構造:
home.rooms()とhome.devices()を使用して部屋とデバイスを取得し、表示しました。 - デバイスの操作: トレイトのコマンドを呼び出して
OnOffPluginUnitDeviceTypeの状態を切り替えるなど、実装されたデバイスの操作。 - 構造の管理: 新しい部屋の作成（
structure.createRoom()）、部屋間のデバイスの移動（structure.move()）、空の部屋の削除（structure.deleteRoom()）の機能を追加しました。 - コミッショニング: SDK のコミッショニング フローを統合して、新しい Matter デバイス（
MatterAddDeviceRequest）を追加しました。 - 自動化: 構造内の自動化を一覧表示、作成（
structure.createAutomation()）、削除（structure.deleteAutomation()）する方法について説明しました。
これで、Home API を活用して iOS でリッチなスマートホーム制御エクスペリエンスを構築する方法の基礎を理解できました。
次のステップ:
- サンプルアプリで提供されている他のデバイスタイプ（照明、扇風機、ブラインドなど）の制御を試してみます。
- さまざまなデバイスで利用できるさまざまな特性とコマンドについて詳しく説明します。
- さまざまな開始条件、条件、アクションを使用して、より複雑な自動化を作成してみましょう。
- より高度な機能と詳細については、Home API のドキュメントをご覧ください。
お疲れさまでした。