1. Einführung

Was sind die Google Home-APIs?
Die Google Home-APIs bieten Entwicklern eine Reihe von Bibliotheken, mit denen sie auf das Google Home-Ökosystem zugreifen können. Mit den Home-APIs können Entwickler Apps erstellen, die Smart-Home-Geräte nahtlos in Betrieb nehmen und steuern.

In diesem Video wird die mobile App, die Sie erstellen, kurz vorgestellt. Sehen Sie sich das Video an, während Sie das Codelab durcharbeiten.
Komponenten der Home APIs
Die Home APIs bestehen aus:
- Device API und Structure API: Mit dem Zuhause eines Nutzers interagieren. Apps können diese APIs verwenden, um Informationen zu Geräten, Räumen und Gebäuden zu lesen (z. B. die aktuelle Thermostattemperatur) und Geräte zu steuern (z. B. den Sollwert des Thermostats zu ändern).
- Commissioning API: Neue Matter-Geräte mit minimalem Aufwand in der Fabric in Betrieb nehmen (einrichten).
- Automation API: Automatisierungen erstellen, löschen und abfragen, die im Zuhause eines Nutzers ausgeführt werden.
Vorbereitung
- Aktuelle stabile Version von Xcode.
- Ein Google-Konto, das mindestens ein Gebäude im Zuhause hat.
- Ein iOS-Gerät mit iOS 16.4 oder höher, das mit dem Testkonto eingerichtet ist.
- Eine Apple-ID, die im Apple Developer Program registriert ist, um das Bereitstellungsprofil zu generieren.
- Einen Google-Hub, der die Home APIs unterstützt.
Lerninhalte
- Anleitung zum Erstellen einer iOS-App mit den Home APIs und Best Practices
- Anleitung zum Verwenden der Geräte- und Gebäude-APIs, um ein Smart Home darzustellen und zu steuern.
- Hier erfährst du, wie du mit der Commissioning API Geräte zum Google Home-Ökosystem hinzufügst.
- Anleitung zum Erstellen einer einfachen Automatisierung mit der Automation API.
2. Zuhause einrichten
Geräte vorbereiten
Der Google Home Playground bietet eine Vielzahl vordefinierter emulierter Smart-Home-Geräte und wird empfohlen, um das volle Potenzial der Home APIs auszuschöpfen, insbesondere wenn du nur eine begrenzte Anzahl von Geräten in deinem Zuhause hast.
Folge der Anleitung, um dich im Google Home Playground anzumelden und die Kontoverknüpfung in der Google Home App abzuschließen. Danach sollten die Geräte in der Google Home App auf dem Tab „Geräte“ angezeigt werden.

3. Einrichtung
Code der Beispiel-App abrufen
Klonen Sie zuerst den Quellcode aus GitHub:
git clone https://github.com/google-home/google-home-api-sample-app-ios.git
Das Beispielverzeichnis enthält zwei Branches für dieses Codelab: start und finished.
start: Der Starter-Code für dieses Projekt, an dem Sie Änderungen vornehmen, um das Codelab abzuschließen.finished: Der vollständige Code für dieses Codelab, mit dem Sie Ihre Arbeit überprüfen können.
Code „start“ ansehen
Wechseln Sie zu Beginn dieses Codelabs zum Zweig start Ihres geklonten Repositorys:
git checkout start
Dieser Zweig enthält den Starter-Code für das Projekt. Sie werden diesen Code im Laufe des Codelabs ändern, um die vollständige Funktionalität zu implementieren. Die Beispiel-App des Codelabs bietet eine grundlegende Struktur in Swift für die Interaktion mit dem iOS SDK für die Home APIs. Hier sind die wichtigsten Komponenten im Projekt start:
Main Entry (GoogleHomeAPISampleIOSApp): Befindet sich inGoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swiftund ist der Haupteinstiegspunkt der Anwendung. Es konfiguriert und initialisiert das SDK und richtet die primäre Benutzeroberfläche ein.Core Views (View/):MainView.swift: Die Stammansicht nach dem Start, die die Haupt-NavigationViewenthält. Sie übernimmt die Auswahl des aktiven Google Home-Zuhause und zeigt die entsprechendeStructureViewan.StructureView.swift: Zeigt den Inhalt für das aktuell ausgewählte Gebäude an. Über Tabs kannst du zwischen einem Raster von Geräten und der Liste Automatisierungen wechseln. Außerdem gibt es Menüs zum Hinzufügen von Räumen oder Geräten.DeviceView.swift: Stellt die interaktive Kachel für ein einzelnes Gerät imStructureView-Raster dar.AutomationsView.swift: Zeigt die Liste der vorhandenen automatisierten Abläufe für das Gebäude an und bietet die Möglichkeit, automatisierte Abläufe zu erstellen oder Details dazu aufzurufen.
ViewModels (ViewModel/): Diese Klassen verwalten den Status und die Logik für die Ansichten.AccountViewModel.swift: Verwaltet die Verbindung zumHome-Objekt und den Authentifizierungsstatus.MainViewModel.swift: Verwaltet die Liste der verfügbarenStructure-Objekte und verfolgt die ausgewählte Struktur.StructureViewModel.swift: Verwaltet die Anzeige von Räumen undDeviceControl-Objekten innerhalb des ausgewählten Gebäudes.AutomationList.swift,AutomationViewModel.swiftusw.: Verarbeitet das Abrufen, Anzeigen, Erstellen und Verwalten von Automatisierungen.
Device Controls (ViewModel/Device/):DeviceControl.swift: Eine Basisklasse zur Darstellung steuerbarer Geräte in der Benutzeroberfläche.- Spezifische Unterklassen (
LightControl.swift,FanControl.swift,OnOffPlugInUnitControl.swiftusw.): Implementieren die UI-Logik, die Gerätesteuerung und die Statuszuordnung für verschiedene Gerätetypen basierend auf ihren Eigenschaften. DeviceControlFactory.swift: Verantwortlich für das Erstellen der entsprechendenDeviceControl-Unterklasse für eine bestimmteHomeDevice.
Commissioning (Commissioning/):CommissioningManager.swift: Enthält die Logik für die Verwaltung des Matter-Geräte-Inbetriebnahmeablaufs.
Utilities & UX (Utils/, UX/, Storage/): Enthält Hilfscode für UI-Elemente (Farben, Abmessungen), Fehlerbehandlung, Datenspeicherung (SelectedStructureStorage.swift) und andere Dienstprogramme.
In diesem Codelab finden Sie Kommentare wie TODO oder auskommentierte Codeblöcke und Benachrichtigungen im Projekt start. Diese markieren die Abschnitte, in denen Sie Code hinzufügen oder die Auskommentierung aufheben, um die erforderliche Funktionalität gemäß den bereitgestellten Schritten zu implementieren.
Apple-Bereitstellungskonfigurationsdateien erstellen
Wenn Sie App Attest konfigurieren möchten, folgen Sie der Anleitung zum Erstellen von Apple-Bereitstellungskonfigurationsdateien. Nach der Einrichtung kann die App nur auf einem echten Gerät bereitgestellt werden, nicht in einem Simulator.
Authentifizierung einrichten
Wenn du die OAuth-Client-ID abrufen und die Home APIs aktivieren möchtest, melde dich zuerst in Google Cloud an und erstelle entweder ein neues Projekt oder wähle ein vorhandenes aus. Folge dann der Anleitung, um die OAuth-Client-ID zu generieren und die Home APIs zu aktivieren, und füge dein Konto der Zulassungsliste hinzu.
SDK einrichten
Lade das iOS SDK für die Home APIs herunter und konfiguriere es gemäß der Anleitung unter SDK einrichten. Ersetzen Sie HOME_API_TODO_ADD_APP_GROUP durch Ihre eigene Anwendungsgruppe.
Projekt erstellen und ausführen
Nachdem Sie das Projekt mit dem Branch start erstellt und ausgeführt haben, sollten ein TODO-Dialogfeld und ein Bildschirm mit der Meldung „Anmeldung erforderlich“ angezeigt werden. Die Interaktion mit den Home APIs wird in den folgenden Abschnitten implementiert.

Hinweis: Suchen Sie im Projekt nach dem im Dialogfeld angezeigten Text, um den Code zu finden, der geändert werden muss. Suchen Sie beispielsweise nach „TODO: initialize Home“.
4. Initialisierung
Zuhause initialisieren
Bevor du eine der Home APIs für iOS verwenden kannst, musst du Home in deiner App initialisieren. Home ist der oberste Einstiegspunkt in das SDK und bietet Zugriff auf alle Entitäten im Gebäude des Nutzers. Wenn Sie alle Entitäten eines bestimmten Typs anfordern, gibt die API ein Query-Objekt zurück, mit dem Sie auswählen können, wie Sie die Ergebnisse erhalten möchten. Entfernen Sie in GoogleHomeAPISampleIOS/Accounts/AccountViewModel.swift den Kommentar und die Benachrichtigung in connect(), um die Initialisierung des Zuhauses zu implementieren.
/// 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).")
}
}
}
Berechtigung zur Verwendung der Home APIs
Der Zustimmungsbildschirm wird angezeigt, wenn du die App ausführst. Wähle das Zuhause in der Google Home App und das Konto aus, das auf der Zulassungsliste deines Google Cloud-Projekts steht.

5. Geräte und Gebäude
Räume und Geräte abrufen
Entferne in GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift den Kommentar und die Benachrichtigung in getRoomsAndDevices(), um die Räume und Geräte im ausgewählten Gebäude mit home.rooms() bzw. home.devices() abzurufen.
/// 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)
}
Die Funktion process() prüft zuerst, ob sich die Geräte im selben Raum befinden, bevor sie die Geräte als HomeDevices mit DeviceControl und DeviceControlFactory interagieren lässt.

Hinweis: Wenn dein Gerät nicht in der DeviceControlFactory aufgeführt ist, wird es als „Nicht unterstützt“ angezeigt. Weitere Informationen zu unterstützten Geräten findest du auf der Seite Unterstützte Gerätetypen unter iOS.
Mit einem Gerät interagieren
Der Stecker outlet1 ist anfangs inaktiv, wenn du auf die Geräte tippst oder darüber wischst. Wenn Sie die Interaktion mit dem Element aktivieren möchten, suchen Sie nach GoogleHomeAPISampleIOS/ViewModel/Device/OnOffPlugInUnitControl.swift und entfernen Sie den Kommentar und die Warnung in der Funktion 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)
}
}
}
Die Funktion primaryAction() in der Klasse OnOffPlugInUnitControl schaltet den Stromstatus einer smarten Steckdose oder eines anderen Geräts, das durch OnOffPluginUnitDeviceType dargestellt wird, um.
Weitere Beispiele für die Gerätesteuerung findest du in GoogleHomeAPISampleIOS/ViewModel/Device.
Neuen Raum erstellen
Mit der Structure API können Räume erstellt und gelöscht sowie Geräte zwischen Räumen verschoben werden.
Entfernen Sie in GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift den Kommentar und die Warnung in 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)")
}
}
}
Wenn du einen neuen Raum mit structure.createRoom() erstellen möchtest, gehe oben links auf das Pluszeichen > „Raum hinzufügen“. Geben Sie den Namen des neuen Raums ein und klicken Sie auf „Raum erstellen“. Der neue Raum wird nach einigen Sekunden angezeigt.

Gerät in einen anderen Raum verschieben
Entfernen Sie in GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift den Kommentar und die Warnung in 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)")
}
}
}
Wenn du das Gerät mit structure.move() an einen anderen Ort verschieben möchtest, halte es gedrückt, wähle „In einen anderen Raum verschieben“ aus und wähle den neuen Raum aus.

Leeren Raum löschen
Entfernen Sie in GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift den Kommentar und die Warnung in 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)")
}
}
}
Wenn Sie einen leeren Raum mit structure.deleteRoom() löschen möchten, klicken Sie rechts neben dem Raumnamen auf das Papierkorbsymbol und bestätigen Sie die Aktion. Hinweis: Es können nur leere Räume gelöscht werden.

Hinweis: Wenn du das Gerät zurückbewegst, wird ein leerer Raum erstellt.
6. Inbetriebnahme
Hinweis: Für diesen Abschnitt sind ein Google-Hub und ein Matter-Gerät erforderlich. Achte darauf, dass der Google-Hub in deinem Gebäude online und erreichbar ist. Wenn du kein Matter-Gerät hast, kannst du stattdessen die App Matter Virtual Device verwenden.
Matter-Gerät hinzufügen
Mit der Commissioning API kann deine App dem Zuhause und dem Google-Konto des Nutzers neue Matter-Geräte hinzufügen. Dies ermöglicht eine nahtlose Einrichtung direkt in deiner App.
Entfernen Sie in GoogleHomeAPISampleIOS/Commissioning/CommissioningManager.swift den Kommentar und die Warnung in 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
}
}
Wenn du einen neuen Raum mit structure.prepareForMatterCommissioning() erstellen möchtest, gehe links oben auf das Pluszeichen > Gerät zu Google Fabric hinzufügen. Dabei wird MatterAddDeviceRequest verwendet, um das Matter-Gerät deinem Raum hinzuzufügen. Nachdem du den Raum und den Gerätenamen ausgewählt hast, wird das Gerät auf dem Bildschirm „Geräte“ angezeigt.

7. Automatisierung
Alle Automatisierungen im Gebäude ansehen
Tippe in der unteren Navigationsleiste auf Automatisierte Abläufe. Hier werden alle automatisierten Abläufe in deinem Gebäude mit structure.listAutomations() aufgeführt.

Hinweis: Wenn du keine automatisierten Abläufe für dein Zuhause eingerichtet hast, wird die Meldung „Füge einen automatisierten Ablauf hinzu, um loszulegen“ angezeigt.
Automatisierung erstellen
Nachdem du dich mit der Device API und der Structure API vertraut gemacht und ein neues Gerät hinzugefügt hast, kannst du jetzt mit der Automation API eine neue Automatisierung erstellen.
Entferne in GoogleHomeAPISampleIOS/ViewModel/Automation/AutomationsRepository.swift den Kommentar, die Benachrichtigung und den leeren automatisierten Ablauf in 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()
}
}
}
Wenn du eine Automatisierung erstellen möchtest, die das Licht fünf Sekunden nach dem Einschalten wieder ausschaltet, gehe zur Automatisierungsansicht und klicke auf + Hinzufügen. Wähle dann Licht nach 5 Sekunden ausschalten aus. Die Automatisierungsdetails, einschließlich starter, condition und action, werden angezeigt. Klicke auf Speichern, um die Automatisierung von structure.createAutomation() zu erstellen.

Hinweis: Welche Automatisierungen verfügbar sind, hängt von den Geräten in deinem Zuhause ab. Wenn keine Automatisierungen verfügbar sind, benenne dein Lichtgerät in „Licht2“ um.
Kehre zum Tab „Geräte“ zurück und schalte die Lampe mit dem Namen „Lampe2“ ein. Sie wird nach fünf Sekunden automatisch deaktiviert.
Eine Automatisierung besteht aus folgenden Komponenten:
- Auslöser: Das ist ein Ereignis, durch das die Automatisierung gestartet wird. In diesem Beispiel würde die Automatisierung gestartet, sobald sich etwas an
OnOffTraitändert. - Bedingung: Es wird geprüft, ob das Auslösergerät bestimmte Anforderungen erfüllt. In diesem Fall wird die Automatisierung ausgeführt, wenn das Licht eingeschaltet ist.
- Aktion: Das ist die Automatisierung, die ausgeführt werden soll, aber nur, wenn der Auslöser die Anforderungen erfüllt. Wenn die Bedingungen erfüllt sind, wird das Licht ausgeschaltet.
Weitere Beispiele findest du auf der Seite Beispiele für Automatisierungen.
Automatisierten Ablauf löschen
Die Methode structure.deleteAutomation() wird aufgerufen, wenn du bei einer vorhandenen Automatisierung nach links wischst und auf das Papierkorbsymbol tippst, um sie aus deinem Gebäude zu entfernen.

8. Glückwunsch
Glückwunsch! Du hast mit den Home APIs für iOS eine einfache Smart-Home-App erstellt.
Was Sie erreicht haben:
- Initialisierung: Du hast deine App über
Home.connect()mit dem Google Home-Ökosystem verbunden. - Berechtigungen: Nutzerauthentifizierung und -autorisierung für den Zugriff auf Smart-Home-Daten.
- Geräte und Gebäude: Räume und Geräte wurden mit
home.rooms()undhome.devices()abgerufen und angezeigt. - Gerätesteuerung: Implementierte Geräteinteraktion, z. B. das Ändern des Status eines
OnOffPluginUnitDeviceTypedurch Aufrufen von Befehlen für seine Eigenschaften. - Gebäudeverwaltung: Es wurden Funktionen zum Erstellen neuer Räume (
structure.createRoom()), zum Verschieben von Geräten zwischen Räumen (structure.move()) und zum Löschen leerer Räume (structure.deleteRoom()) hinzugefügt. - Inbetriebnahme: Der Ablauf für die Inbetriebnahme des SDK wurde integriert, um neue Matter-Geräte (
MatterAddDeviceRequest) hinzuzufügen. - Automatisierung: Sie haben gelernt, wie Sie Automatisierungen in einer Struktur auflisten, erstellen (
structure.createAutomation()) und löschen (structure.deleteAutomation()).
Du hast jetzt ein grundlegendes Verständnis davon, wie du die Home APIs nutzen kannst, um umfangreiche Smart-Home-Steuerungen für iOS zu entwickeln.
Nächste Schritte
- Probiere aus, wie du andere Gerätetypen in der Beispiel-App steuern kannst (Lampen, Ventilatoren, Jalousien usw.).
- Hier findest du weitere Informationen zu den verschiedenen Eigenschaften und Befehlen, die für verschiedene Geräte verfügbar sind.
- Experimentiere mit verschiedenen Auslösern, Bedingungen und Aktionen, um komplexere automatisierte Abläufe zu erstellen.
- Weitere Informationen und erweiterte Funktionen findest du in der Dokumentation zu den Google Home-APIs.
Gut gemacht!