1. Wprowadzenie

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ą.

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
- Najnowsza stabilna wersja Xcode.
- Konto Google, które ma co najmniej 1 strukturę w domu.
- urządzenie z iOS w wersji 16.4 lub nowszej skonfigurowane z kontem testowym,
- Identyfikator Apple zarejestrowany w programie Apple Developer Program, aby wygenerować profil obsługi administracyjnej.
- Centrum Google, które obsługuje interfejsy API Google Home.
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.

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ę wGoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swifti 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 elementNavigationView. Odpowiada za wybór aktywnego domu Google Home i wyświetla odpowiedniStructureView.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 siatceStructureView.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 obiektemHomei zarządza stanem uwierzytelniania.MainViewModel.swift: zarządza listą dostępnych obiektówStructurei śledzi wybraną strukturę.StructureViewModel.swift: zarządza wyświetlaniem pomieszczeń i obiektówDeviceControlw wybranej strukturze.AutomationList.swift,AutomationViewModel.swiftitd.: 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.swiftitd.): 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 podklasyDeviceControldla danegoHomeDevice.
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.

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.

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.

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.

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.

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.

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”.

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().

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().

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.

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()ihome.devices(). - Sterowanie urządzeniem: zaimplementowano interakcję z urządzeniem, np. przełączanie stanu urządzenia
OnOffPluginUnitDeviceTypeprzez 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!