Mobile App mit den Home APIs auf iOS erstellen

1. Einführung

f154e30306882c74.png

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.

3e11583c779a2cec.png

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

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.

c892afce113abe8f.png

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 in GoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swift und 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-NavigationView enthält. Sie übernimmt die Auswahl des aktiven Google Home-Zuhause und zeigt die entsprechende StructureView an.
    • 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 im StructureView-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 zum Home-Objekt und den Authentifizierungsstatus.
    • MainViewModel.swift: Verwaltet die Liste der verfügbaren Structure-Objekte und verfolgt die ausgewählte Struktur.
    • StructureViewModel.swift: Verwaltet die Anzeige von Räumen und DeviceControl-Objekten innerhalb des ausgewählten Gebäudes.
    • AutomationList.swift, AutomationViewModel.swift usw.: 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.swift usw.): 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 entsprechenden DeviceControl-Unterklasse für eine bestimmte HomeDevice.
  • 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.

bd56b7080037e38a.png 9c0f08a3f4197a77.png

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.

47310f458c0094d9.png 4a571dbd9979a88c.png e29c75891a3a67af.png

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.

4c677c4c294e67ca.png

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.

b122ae6642b7da1c.png a45f785e1d51938e.png 7753b56cbdcff8d6.png

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.

f9627592af44163d.png fd126fabb454f2bf.png 813e1e23e50cd9f6.png

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.

4f129262ad67f564.png

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.

adf6cbb531787aaf.png f002bd6320bc480d.png

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.

cc6d50f72f812c24.png

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.

21c1f8ea2a29134b.png 4bd36f6ed9c5f6e9.png

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.

dc678cd9e16f89a5.png

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() und home.devices() abgerufen und angezeigt.
  • Gerätesteuerung: Implementierte Geräteinteraktion, z. B. das Ändern des Status eines OnOffPluginUnitDeviceType durch 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!