Tworzenie aplikacji mobilnej przy użyciu interfejsów API Home na iOS

1. Wprowadzenie

f154e30306882c74.png

Czym są interfejsy API Google Home?

Interfejsy API Google Home udostępniają zestaw bibliotek, dzięki którym deweloperzy mogą korzystać z ekosystemu Google Home. Dzięki interfejsom API Google Home deweloperzy mogą tworzyć aplikacje, które bezproblemowo uruchamiają inteligentne urządzenia domowe i nimi sterują.

3e11583c779a2cec.png

Ten film zawiera krótkie omówienie aplikacji mobilnej, którą będziesz tworzyć. Obejrzyj go, wykonując ćwiczenie.

Komponenty interfejsów API Google Home

Interfejsy API Google Home składają się z tych elementów:

  • Interfejsy Device API i Structure API: interakcja z domem użytkownika. Aplikacje mogą używać tych interfejsów API do odczytywania informacji o urządzeniach, pomieszczeniach i domach (np. do sprawdzania bieżącej temperatury na termostacie) oraz do sterowania urządzeniami (np. do zmiany nastawy termostatu).
  • Commissioning API: umożliwia łatwe konfigurowanie nowych urządzeń Matter w sieci.
  • Automation API: tworzenie, usuwanie i wykonywanie zapytań dotyczących automatyzacji działających w domu użytkownika.

Wymagania wstępne

Czego się nauczysz

  • Jak utworzyć aplikację na iOS za pomocą interfejsów API Google Home zgodnie ze sprawdzonymi metodami.
  • Jak używać interfejsów Device API i Structure API do reprezentowania inteligentnego domu i sterowania nim.
  • Jak używać interfejsu Commissioning API do dodawania urządzeń do ekosystemu Google Home.
  • Jak używać interfejsu Automation API do tworzenia podstawowej automatyzacji.

2. Konfigurowanie domu

Przygotowanie urządzeń

Google Home Playground oferuje różne gotowe emulowane inteligentne urządzenia domowe i jest zalecany do poznawania pełnego potencjału interfejsów API Google Home, zwłaszcza jeśli masz w domu ograniczoną liczbę urządzeń.

Postępuj zgodnie z instrukcjami, aby zalogować się w Google Home Playground i połączyć konto w aplikacji Google Home. Po wykonaniu tych czynności urządzenia powinny być widoczne na karcie „Urządzenia” w aplikacji Google Home.

c892afce113abe8f.png

3. Przygotowania

Pobieranie kodu przykładowej aplikacji

Zacznij od sklonowania kodu źródłowego z GitHuba:

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

Katalog z przykładami zawiera 2 gałęzie, start i finished, dla tego ćwiczenia z programowania.

  • start: kod startowy tego projektu, w którym wprowadzisz zmiany, aby ukończyć ćwiczenia z programowania.
  • finished: gotowy kod z tego ćwiczenia, który służy do sprawdzania Twojej pracy.

Przeglądanie kodu „start”

Zacznij tego codelaba od przełączenia się na gałąź start sklonowanego repozytorium:

git checkout start

Ta gałąź zawiera kod startowy projektu. W trakcie tego ćwiczenia będziesz modyfikować ten kod, aby zaimplementować pełną funkcjonalność. Przykładowa aplikacja w ćwiczeniu zawiera podstawową strukturę utworzoną w języku Swift, która umożliwia interakcję z pakietem SDK interfejsów API Google Home na iOS. Oto najważniejsze komponenty projektu start:

  • Main Entry (GoogleHomeAPISampleIOSApp): znajduje się w GoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swift i jest głównym punktem wejścia aplikacji. Konfiguruje i inicjuje pakiet SDK oraz konfiguruje podstawowy interfejs użytkownika.
  • Core Views (View/):
    • MainView.swift: widok główny po uruchomieniu, zawierający główny element NavigationView. Odpowiada za wybór aktywnego domu Google Home i wyświetla odpowiedni StructureView.
    • StructureView.swift: wyświetla zawartość aktualnie wybranego domu, umożliwiając przełączanie się między siatką Urządzenia a listą Automatyzacja. Znajdziesz tam też menu umożliwiające dodawanie pomieszczeń i urządzeń.
    • DeviceView.swift: reprezentuje interaktywny kafelek pojedynczego urządzenia w siatce StructureView.
    • AutomationsView.swift: wyświetla listę istniejących automatyzacji dla budynku i umożliwia przejście do tworzenia lub wyświetlania szczegółów automatyzacji.
  • ViewModels (ViewModel/): te klasy zarządzają stanem i logiką widoków.
    • AccountViewModel.swift: obsługuje połączenie z obiektem Home i zarządza stanem uwierzytelniania.
    • MainViewModel.swift: zarządza listą dostępnych obiektów Structure i śledzi wybraną strukturę.
    • StructureViewModel.swift: zarządza wyświetlaniem pomieszczeń i obiektów DeviceControl w wybranej strukturze.
    • AutomationList.swift, AutomationViewModel.swift itd.: obsługuje pobieranie, wyświetlanie, tworzenie automatyzacji i zarządzanie nimi.
  • Device Controls (ViewModel/Device/):
    • DeviceControl.swift: klasa bazowa do reprezentowania urządzeń, którymi można sterować, w interfejsie.
    • Konkretne podklasy (LightControl.swift, FanControl.swift, OnOffPlugInUnitControl.swift itd.): implementują logikę interfejsu, sterowanie urządzeniem i mapowanie stanu dla różnych typów urządzeń na podstawie ich cech.
    • DeviceControlFactory.swift: odpowiada za utworzenie odpowiedniej podklasy DeviceControl dla danego HomeDevice.
  • Commissioning (Commissioning/):
    • CommissioningManager.swift: zawiera logikę zarządzania procesem dodawania urządzenia Matter.
  • Utilities & UX (Utils/, UX/, Storage/): zawiera kod pomocniczy dla elementów interfejsu (kolory, wymiary), obsługę błędów, magazyn danych (SelectedStructureStorage.swift) i inne narzędzia.

W tym ćwiczeniu znajdziesz komentarze takie jak TODO lub zmienione w komentarze bloki kodu i alerty w projekcie start. Oznaczają one sekcje, w których dodasz lub usuniesz znacznik komentarza z kodu, aby zaimplementować wymaganą funkcję zgodnie z podanymi instrukcjami.

Tworzenie plików konfiguracji wdrożenia Apple

Aby skonfigurować App Attest, postępuj zgodnie z instrukcjami tworzenia plików konfiguracji wdrożenia Apple. Pamiętaj, że po skonfigurowaniu aplikację można wdrożyć tylko na prawdziwym urządzeniu, a nie w symulatorze.

Konfigurowanie uwierzytelniania

Aby uzyskać identyfikator klienta OAuth i włączyć interfejsy API Google Home, najpierw zaloguj się w Google Cloud i utwórz nowy projekt lub wybierz istniejący. Następnie wykonaj podane czynności, aby wygenerować identyfikator klienta OAuth i włączyć interfejsy API Google Home oraz dodać swoje konto do listy dozwolonych.

Konfigurowanie pakietu SDK

Pobierz pakiet SDK interfejsów API Google Home na iOS i skonfiguruj go zgodnie z instrukcjami podanymi w sekcji Konfigurowanie pakietu SDK. Pamiętaj, aby zastąpić HOME_API_TODO_ADD_APP_GROUP własną grupą aplikacji.

Tworzenie i uruchamianie projektu

Po utworzeniu i uruchomieniu projektu z gałęzią start powinno pojawić się okno dialogowe TODO i ekran z komunikatem „Wymagane zalogowanie”. Interakcja z interfejsami API Google Home zostanie zaimplementowana w kolejnych sekcjach.

bd56b7080037e38a.png 9c0f08a3f4197a77.png

Uwaga: znajdź kod, który należy zmodyfikować, wyszukując w projekcie tekst wyświetlany w oknie. Na przykład wyszukaj „TODO: initialize Home”.

4. Zdarzenie inicjujące

Inicjowanie strony głównej

Zanim użyjesz interfejsów API Google Home na iOS, musisz zainicjować Home w aplikacji. Home to najwyższy poziom dostępu do pakietu SDK, który umożliwia dostęp do wszystkich encji w domu użytkownika. Gdy wysyłasz żądanie dotyczące wszystkich encji określonego typu, interfejs API zwraca obiekt Query, który pozwala wybrać sposób otrzymywania wyników. W pliku GoogleHomeAPISampleIOS/Accounts/AccountViewModel.swift usuń komentarz i alert w pliku connect(), aby zaimplementować inicjowanie strony głównej.

  /// 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).")
      }
    }
  }

Uprawnienia do korzystania z interfejsów API Google Home

Po uruchomieniu aplikacji pojawi się ekran zgody. Wybierz strukturę Google Home i konto, które znajduje się na liście dozwolonych w projekcie w chmurze Google Cloud.

47310f458c0094d9.png 4a571dbd9979a88c.png e29c75891a3a67af.png

5. Urządzenia i domy

Pobieranie informacji o salach i urządzeniach

W pliku GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift usuń komentarz i alert w pliku getRoomsAndDevices(), aby uzyskać pomieszczenia i urządzenia w wybranej strukturze, odpowiednio z home.rooms() i 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)
  }

Funkcja process() najpierw sprawdza, czy urządzenia znajdują się w tym samym pomieszczeniu, a następnie umożliwia im interakcję jako HomeDevices przy użyciu DeviceControl i DeviceControlFactory.

4c677c4c294e67ca.png

Uwaga: jeśli Twojego urządzenia nie ma na liście DeviceControlFactory, będzie ono wyświetlane jako „Nieobsługiwane”. Więcej informacji o obsługiwanych urządzeniach znajdziesz na stronie Obsługiwane typy urządzeń na iOS.

Interakcja z urządzeniem

Wtyczka outlet1 jest początkowo nieaktywna, gdy klikasz lub przesuwasz palcem po urządzeniach. Aby umożliwić interakcję z nim, znajdź GoogleHomeAPISampleIOS/ViewModel/Device/OnOffPlugInUnitControl.swift i usuń komentarz oraz alert w funkcji 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)
      }
    }
  }

Funkcja primaryAction(), która znajduje się w klasie OnOffPlugInUnitControl, przełącza stan zasilania inteligentnej wtyczki lub dowolnego urządzenia reprezentowanego przez OnOffPluginUnitDeviceType.

Dodatkowe przykłady sterowania urządzeniami znajdziesz w GoogleHomeAPISampleIOS/ViewModel/Device.

Tworzenie nowego pomieszczenia

Interfejs Structure API umożliwia tworzenie i usuwanie pomieszczeń oraz przenoszenie urządzeń między pomieszczeniami.

W GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift usuń komentarz i alert w 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)")
      }
    }
  }

Aby utworzyć nowy pokój za pomocą structure.createRoom(), w lewym górnym rogu kliknij ikonę „+” > Dodaj pokój. Wpisz nową nazwę pokoju i kliknij „Utwórz pokój”. Nowe pomieszczenie pojawi się po kilku sekundach.

b122ae6642b7da1c.png a45f785e1d51938e.png 7753b56cbdcff8d6.png

Przenoszenie urządzenia do innego pomieszczenia

W GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift usuń komentarz i alert w 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)")
      }
    }
  }

Aby przenieść urządzenie za pomocą aplikacji structure.move(), naciśnij je i przytrzymaj, wybierz „Przenieś do innego pomieszczenia” i wybierz nowe pomieszczenie.

f9627592af44163d.png fd126fabb454f2bf.png 813e1e23e50cd9f6.png

Usuwanie pustego pokoju

W GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift usuń komentarz i alert w 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)")
      }
    }
  }

Aby usunąć pusty pokój z structure.deleteRoom(), kliknij ikonę kosza po prawej stronie nazwy pokoju i potwierdź działanie. Pamiętaj, że można usuwać tylko puste pokoje.

4f129262ad67f564.png

Uwaga: aby utworzyć pusty pokój, przesuń urządzenie do tyłu.

6. Uruchomienie

Uwaga: ta sekcja wymaga centrum Google i urządzenia Matter. Upewnij się, że urządzenie Google hub w Twoim domu jest online i dostępne. Jeśli nie masz urządzenia Matter, spróbuj użyć aplikacji Matter Virtual Device.

Dodawanie urządzenia Matter

Commissioning API umożliwia aplikacji dodawanie nowych urządzeń Matter do domu i konta Google użytkownika. Zapewnia to łatwą konfigurację bezpośrednio w aplikacji.

W GoogleHomeAPISampleIOS/Commissioning/CommissioningManager.swift usuń komentarz i alert w 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
    }
  }

Aby utworzyć nowe pomieszczenie z urządzeniem structure.prepareForMatterCommissioning(), w lewym górnym rogu kliknij ikonę „+” > Dodaj urządzenie do Google Fabric. Używa MatterAddDeviceRequest, aby dodać urządzenie Matter do pomieszczenia. Po wybraniu pomieszczenia i nazwy urządzenia pojawi się ono na ekranie „Urządzenia”.

adf6cbb531787aaf.png f002bd6320bc480d.png

7. Automatyzacja

Wyświetlanie wszystkich automatyzacji w domu

Na dolnym pasku nawigacyjnym kliknij Automatyzacje. Wyświetli się lista wszystkich automatyzacji w domu, które mają structure.listAutomations().

cc6d50f72f812c24.png

Uwaga: jeśli nie masz skonfigurowanych żadnych automatyzacji domowych, zobaczysz komunikat „Aby rozpocząć, dodaj automatyzację”.

Utwórz automatyzację

Teraz, gdy znasz już interfejsy Device API i Structure API oraz wiesz, jak dodać nowe urządzenie, możesz utworzyć nową automatyzację za pomocą interfejsu Automation API.

W pliku GoogleHomeAPISampleIOS/ViewModel/Automation/AutomationsRepository.swift usuń komentarz, alert i pustą automatyzację w pliku 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()
      }
    }
  }

Aby utworzyć automatyzację, która wyłączy światło 5 sekund po jego włączeniu, przejdź do widoku automatyzacji i kliknij przycisk + Dodaj. Następnie wybierz „Wyłącz światło po 5 sekundach”. Wyświetlą się szczegóły automatyzacji, w tym starter, condition i action. Kliknij „Zapisz”, aby utworzyć automatyzację przez structure.createAutomation().

21c1f8ea2a29134b.png 4bd36f6ed9c5f6e9.png

Uwaga: dostępne automatyzacje zależą od urządzeń w Twoim domu. Jeśli nie widzisz żadnych dostępnych automatyzacji, spróbuj zmienić nazwę urządzenia oświetleniowego na „światło2”.

Wróć na kartę „Urządzenia” i włącz światło o nazwie „światło2”. Wyłączy się automatycznie po 5 sekundach.

Komponenty automatyzacji:

  • Polecenie inicjujące: to zdarzenie, które uruchamia automatyzację. W tym przykładzie automatyzacja zostanie uruchomiona, gdy nastąpi zmiana w: OnOffTrait.
  • Warunek: sprawdza, czy urządzenie inicjujące spełnia określone wymagania. W takim przypadku automatyzacja zostanie wykonana, jeśli światło jest włączone.
  • Działanie: to automatyzacja, którą chcesz wykonać, ale tylko wtedy, gdy zdarzenie inicjujące spełnia wymagania. Jeśli warunki są spełnione, światło zostanie wyłączone.

Więcej przykładów znajdziesz na stronie Przykładowe automatyzacje.

Usuwanie automatyzacji

Metoda structure.deleteAutomation() jest wywoływana, gdy przesuwasz palcem w lewo po istniejącej automatyzacji i klikasz ikonę kosza, aby usunąć ją z domu.

dc678cd9e16f89a5.png

8. Gratulacje

Gratulacje! Udało Ci się utworzyć podstawową aplikację do inteligentnego domu za pomocą interfejsów API Google Home na iOS.

Co udało Ci się osiągnąć:

  • Inicjowanie: połącz aplikację z ekosystemem Google Home za pomocą Home.connect().
  • Uprawnienia: obsługa uwierzytelniania i autoryzacji użytkowników w celu uzyskania dostępu do danych domu.
  • Urządzenia i domy: pobrano i wyświetlono pomieszczenia oraz urządzenia za pomocą home.rooms() i home.devices().
  • Sterowanie urządzeniem: zaimplementowano interakcję z urządzeniem, np. przełączanie stanu urządzenia OnOffPluginUnitDeviceType przez wywoływanie poleceń dotyczących jego cech.
  • Zarządzanie domem: dodano funkcje tworzenia nowych pomieszczeń (structure.createRoom()), przenoszenia urządzeń między pomieszczeniami (structure.move()) i usuwania pustych pomieszczeń (structure.deleteRoom()).
  • Uruchamianie: zintegrowano proces uruchamiania pakietu SDK, aby umożliwić dodawanie nowych urządzeń Matter (MatterAddDeviceRequest).
  • Automatyzacja: dowiedzieliśmy się, jak wyświetlać, tworzyć (structure.createAutomation()) i usuwać (structure.deleteAutomation()) automatyzacje w domu.

Masz już podstawową wiedzę na temat korzystania z interfejsów API Google Home do tworzenia rozbudowanych funkcji sterowania inteligentnym domem na iOS.

Dalsze kroki:

  • Spróbuj sterować innymi typami urządzeń dostępnymi w przykładowej aplikacji (światła, wentylatory, rolety itp.).
  • Poznaj bliżej różne cechy i polecenia dostępne na różnych urządzeniach.
  • Eksperymentuj z tworzeniem bardziej złożonych automatyzacji, używając różnych aktywatorów, warunków i działań.
  • Więcej informacji o zaawansowanych funkcjach znajdziesz w dokumentacji interfejsów API Google Home.

Brawo!