1. Introduction

Que sont les API Home ?
Les API Google Home fournissent un ensemble de bibliothèques permettant aux développeurs d'exploiter l'écosystème Google Home. Grâce aux API Home, les développeurs peuvent créer des applications qui mettent en service et contrôlent facilement les appareils connectés.

Cette vidéo présente brièvement l'application mobile que vous allez créer. Suivez-la tout en effectuant l'atelier de programmation.
Composants des API Home
Les API Home sont composées des éléments suivants :
- API Device et Structure : interagissez avec la maison d'un utilisateur. Les applications peuvent utiliser ces API pour lire des informations sur les appareils, les pièces et les structures (par exemple, pour voir la température actuelle du thermostat) et contrôler les appareils (par exemple, pour modifier la température mémorisée du thermostat).
- API Commissioning : mettez en service (configurez) de nouveaux appareils Matter dans le fabric avec un minimum d'effort.
- API Automation : créez, supprimez et interrogez des automatisations exécutées dans la maison d'un utilisateur.
Prérequis
- La dernière version stable de Xcode
- Un compte Google associé à au moins une structure dans la maison.
- Un appareil iOS doté d'iOS 16.4 ou version ultérieure, configuré avec le compte de test.
- Un identifiant Apple enregistré dans le Apple Developer Program afin de générer le profil de provisionnement.
- Un hub Google compatible avec les API Home.
Points abordés
- Comment créer une application iOS à l'aide des API Home en suivant les bonnes pratiques.
- Utiliser les API Device et Structure pour représenter et contrôler une maison connectée
- Utiliser l'API Commissioning pour ajouter des appareils à l'écosystème Google Home
- Comment utiliser l'API Automation pour créer une automatisation de base.
2. Configurer votre maison
Préparer les appareils
Le Playground Google Home propose une variété d'appareils connectés émulés prédéfinis. Il est recommandé pour explorer tout le potentiel des API Home, en particulier si vous avez un nombre limité d'appareils chez vous.
Suivez les instructions pour vous connecter à Google Home Playground et associer votre compte dans l'application Google Home. Vous devriez ensuite voir les appareils dans l'onglet "Appareils" de l'application Google Home.

3. Configuration
Obtenir le code de l'application exemple
Commencez par cloner le code source depuis GitHub :
git clone https://github.com/google-home/google-home-api-sample-app-ios.git
Le répertoire d'exemples contient deux branches, start et finished, pour cet atelier de programmation.
start: code de démarrage du projet, que vous allez modifier tout au long de l'atelier de programmation.finished: code final de cet atelier de programmation (pour vérifier ce que vous avez fait).
Se familiariser avec le code de démarrage
Commencez cet atelier de programmation en passant à la branche start de votre dépôt cloné :
git checkout start
Cette branche contient le code de démarrage du projet. Vous allez modifier ce code tout au long de l'atelier de programmation pour implémenter l'ensemble des fonctionnalités. L'application exemple de l'atelier de programmation fournit une structure de base créée en Swift pour interagir avec le SDK iOS des API Home. Voici les principaux composants du projet start :
Main Entry (GoogleHomeAPISampleIOSApp): situé dansGoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swift, il s'agit du point d'entrée principal de l'application. Il configure et initialise le SDK, et configure l'interface utilisateur principale.Core Views (View/):MainView.swift: vue racine après le lancement, contenant leNavigationViewprincipal. Il gère la sélection de la structure Google Home active et affiche leStructureViewcorrespondant.StructureView.swift: affiche le contenu de la structure actuellement sélectionnée, en utilisant des onglets pour basculer entre une grille d'appareils et la liste des automatisations. Elle fournit également des menus permettant d'ajouter des pièces ou des appareils.DeviceView.swift: représente la tuile interactive d'un seul appareil dans la grilleStructureView.AutomationsView.swift: affiche la liste des automatisations existantes pour la structure et permet de créer ou d'afficher les détails d'une automatisation.
ViewModels (ViewModel/): ces classes gèrent l'état et la logique des vues.AccountViewModel.swift: gère la connexion à l'objetHomeet l'état d'authentification.MainViewModel.swift: gère la liste des objetsStructuredisponibles et effectue le suivi de la structure sélectionnée.StructureViewModel.swift: gère l'affichage des pièces et des objetsDeviceControldans la structure sélectionnée.AutomationList.swift,AutomationViewModel.swift, etc. : gère la récupération, l'affichage, la création et la gestion des automatisations.
Device Controls (ViewModel/Device/):DeviceControl.swift: classe de base permettant de représenter les appareils contrôlables dans l'interface utilisateur.- Sous-classes spécifiques (
LightControl.swift,FanControl.swift,OnOffPlugInUnitControl.swift, etc.) : implémentent la logique d'interface utilisateur, le contrôle de l'appareil et le mappage d'état pour différents types d'appareils en fonction de leurs caractéristiques. DeviceControlFactory.swift: responsable de la création de la sous-classeDeviceControlappropriée pour unHomeDevicedonné.
Commissioning (Commissioning/):CommissioningManager.swift: contient la logique de gestion du flux de mise en service de l'appareil Matter.
Utilities & UX (Utils/, UX/, Storage/): contient le code d'assistance pour les éléments d'interface utilisateur (couleurs, dimensions), la gestion des exceptions, le datastore (SelectedStructureStorage.swift) et d'autres utilitaires.
Tout au long de cet atelier de programmation, vous trouverez des commentaires tels que TODO, des blocs de code commentés et des alertes dans le projet start. Ils indiquent les sections où vous ajouterez ou annulerez la mise en commentaire du code pour implémenter la fonctionnalité requise, en suivant les étapes fournies.
Créer des fichiers de configuration de déploiement Apple
Pour configurer App Attest, suivez les instructions de création des fichiers de configuration de déploiement Apple. Notez qu'après la configuration, l'application ne peut être déployée que sur un appareil réel, et non dans un simulateur.
Configurer l'authentification
Pour obtenir l'ID client OAuth et activer les API Home, commencez par vous connecter à Google Cloud, puis créez un projet ou sélectionnez-en un existant. Suivez ensuite la procédure pour générer l'ID client OAuth et activer les API Home, puis ajoutez votre compte à la liste d'autorisation.
Configurez le SDK
Obtenez le SDK iOS des API Home et configurez-le en suivant les instructions de configuration fournies dans Configurer le SDK. N'oubliez pas de remplacer HOME_API_TODO_ADD_APP_GROUP par votre propre groupe d'applications.
Créer et exécuter le projet
Après avoir compilé et exécuté le projet avec la branche start, une boîte de dialogue TODO et un écran affichant "Connexion requise" devraient s'afficher. L'interaction avec les API Home sera implémentée dans les sections suivantes.

Remarque : Recherchez le code à modifier en recherchant dans le projet le texte affiché dans la boîte de dialogue. Par exemple, recherchez "TODO: initialize Home".
4. Initialisation
Initialiser la maison
Avant d'utiliser les API Home pour iOS, vous devez initialiser Home dans votre application. Home est l'entrée de niveau supérieur du SDK et permet d'accéder à toutes les entités de la structure de l'utilisateur. Lorsque vous demandez toutes les entités d'un type particulier, l'API renvoie un objet Query qui vous permet de choisir comment recevoir les résultats. Dans GoogleHomeAPISampleIOS/Accounts/AccountViewModel.swift, supprimez le commentaire et l'alerte dans connect() pour implémenter l'initialisation de la page d'accueil.
/// 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).")
}
}
}
Autorisation d'utiliser les API Home
L'écran de consentement s'affiche lorsque vous exécutez l'application. Choisissez la structure de maison Google Home et sélectionnez le compte figurant sur la liste d'autorisation de votre projet Google Cloud.

5. Appareils et structures
Obtenir des pièces et des appareils
Dans GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, supprimez le commentaire et l'alerte dans getRoomsAndDevices() pour obtenir les pièces et les appareils de la structure sélectionnée avec home.rooms() et home.devices(), respectivement.
/// 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)
}
La fonction process() vérifie d'abord que les appareils se trouvent dans la même pièce avant de les faire interagir en tant que HomeDevices à l'aide de DeviceControl et DeviceControlFactory.

Remarque : Si votre appareil ne figure pas dans la DeviceControlFactory, il s'affiche comme "Non compatible". Pour en savoir plus sur les appareils compatibles, consultez la page Types d'appareils compatibles sur iOS.
Interagir avec un appareil
Le plug-in outlet1 est initialement inactif lorsque vous appuyez ou faites glisser votre doigt sur les appareils. Pour activer l'interaction avec ce bouton, recherchez GoogleHomeAPISampleIOS/ViewModel/Device/OnOffPlugInUnitControl.swift, puis supprimez le commentaire et l'alerte dans la fonction 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)
}
}
}
La fonction primaryAction(), qui se trouve dans la classe OnOffPlugInUnitControl, permet d'activer ou de désactiver l'état d'alimentation d'une prise connectée ou de tout appareil représenté par OnOffPluginUnitDeviceType.
D'autres exemples de contrôle des appareils sont disponibles dans GoogleHomeAPISampleIOS/ViewModel/Device.
Créer une pièce
L'API Structure permet de créer et de supprimer des pièces, ainsi que de transférer des appareils entre les pièces.
Dans GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, supprimez le commentaire et l'alerte dans 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)")
}
}
}
Pour créer une pièce avec structure.createRoom(), accédez à l'angle supérieur gauche, puis sélectionnez l'icône "+" > Ajouter une pièce. Saisissez le nom de votre nouvelle pièce, puis cliquez sur "Créer une pièce". La nouvelle pièce s'affiche au bout de quelques secondes.

Déplacer un appareil dans une autre pièce
Dans GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, supprimez le commentaire et l'alerte dans 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)")
}
}
}
Pour déplacer l'appareil avec structure.move(), appuyez de manière prolongée dessus, sélectionnez "Déplacer vers une autre pièce", puis choisissez la nouvelle pièce.

Supprimer une salle vide
Dans GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, supprimez le commentaire et l'alerte dans 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)")
}
}
}
Pour supprimer un salon vide avec structure.deleteRoom(), cliquez sur l'icône de corbeille à droite du nom du salon, puis confirmez l'action. Notez que seules les salles vides peuvent être supprimées.

Remarque : Déplacez l'appareil pour créer une pièce vide.
6. Mise en service
Remarque : Cette section nécessite un hub Google et un appareil Matter. Assurez-vous que le hub Google de votre structure est en ligne et accessible. Si vous n'avez pas d'appareil Matter, essayez d'utiliser l'application Matter Virtual Device.
Ajouter un appareil Matter
L'API Commissioning permet à votre application d'ajouter de nouveaux appareils Matter à la maison et au compte Google de l'utilisateur. Cela permet de configurer l'appareil de manière fluide directement dans votre application.
Dans GoogleHomeAPISampleIOS/Commissioning/CommissioningManager.swift, supprimez le commentaire et l'alerte dans 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
}
}
Pour créer une pièce avec structure.prepareForMatterCommissioning(), accédez à l'angle supérieur gauche, puis sélectionnez l'icône "+" > Ajouter un appareil à Google Fabric. Il utilise MatterAddDeviceRequest pour ajouter l'appareil Matter à votre pièce. Une fois que vous avez sélectionné la pièce et le nom de l'appareil, celui-ci s'affiche sur l'écran "Appareils".

7. Automatisation
Afficher toutes les automatisations de la structure
Appuyez sur Automatisations dans la barre de navigation inférieure. Toutes les automatisations de votre structure s'affichent avec structure.listAutomations().

Remarque : Si vous n'avez configuré aucune automatisation de la maison, le message "Ajoutez une automatisation pour commencer" s'affiche.
Créer une automatisation
Maintenant que vous connaissez les API Device et Structure, et que vous savez ajouter un nouvel appareil, vous allez créer une automatisation à l'aide de l'API Automation.
Dans GoogleHomeAPISampleIOS/ViewModel/Automation/AutomationsRepository.swift, supprimez le commentaire, l'alerte et l'automatisation vide dans 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()
}
}
}
Pour créer une automatisation qui éteindra la lumière cinq secondes après son allumage, accédez à la vue des automatisations, puis cliquez sur le bouton + Ajouter. Sélectionnez ensuite Éteindre la lumière après 5 secondes. Les détails de l'automatisation s'affichent, y compris les champs starter, condition et action. Cliquez sur Enregistrer pour créer l'automatisation par structure.createAutomation().

Remarque : Les automatisations disponibles dépendent des appareils de votre maison. Si aucune automatisation n'est disponible, essayez de renommer votre appareil d'éclairage en "lumière2".
Revenez à l'onglet "Appareils" et allumez la lumière nommée "light2". Il s'éteindra automatiquement au bout de cinq secondes.
Les composants d'une automatisation sont les suivants :
- Déclencheur : événement qui lance l'automatisation. Dans cet exemple, l'automatisation démarre dès qu'un changement est détecté sur
OnOffTrait. - Condition : vérifie si l'appareil de déclenchement remplit des conditions spécifiques. Dans ce cas, l'automatisation s'exécute si la lumière est allumée.
- Action : automatisation que vous souhaitez effectuer, mais uniquement si le déclencheur remplit les conditions requises. Si les conditions sont remplies, la lumière s'éteint.
Pour d'autres exemples, consultez la page Exemples d'automatisations.
Supprimer une automatisation
La méthode structure.deleteAutomation() est appelée lorsque vous balayez vers la gauche une automatisation existante et que vous appuyez sur l'icône de la corbeille pour la supprimer de votre structure.

8. Félicitations
Félicitations ! Vous avez créé une application de base pour la maison connectée à l'aide des API Home pour iOS.
Ce que vous avez accompli :
- Initialisation : vous avez connecté votre application à l'écosystème Google Home à l'aide de
Home.connect(). - Autorisations : gère l'authentification et l'autorisation des utilisateurs pour l'accès aux données de la maison.
- Appareils et structures : récupération et affichage des pièces et des appareils à l'aide de
home.rooms()ethome.devices(). - Contrôle de l'appareil : implémentation de l'interaction avec l'appareil, par exemple en activant/désactivant l'état d'un
OnOffPluginUnitDeviceTypeen appelant des commandes sur ses caractéristiques. - Gestion des structures : ajout de fonctionnalités permettant de créer des pièces (
structure.createRoom()), de déplacer des appareils entre les pièces (structure.move()) et de supprimer des pièces vides (structure.deleteRoom()). - Mise en service : intégration du flux de mise en service du SDK pour ajouter de nouveaux appareils Matter (
MatterAddDeviceRequest). - Automatisation : vous avez appris à lister, créer (
structure.createAutomation()) et supprimer (structure.deleteAutomation()) des automatisations dans une structure.
Vous maîtrisez désormais les bases de l'utilisation des API Home pour créer des expériences de contrôle de la maison connectée enrichies sur iOS.
Étapes suivantes :
- Essayez de contrôler d'autres types d'appareils fournis dans l'application exemple (lumières, ventilateurs, stores, etc.).
- Découvrez plus en détail les différents traits et commandes disponibles pour divers appareils.
- Essayez de créer des automatisations plus complexes à l'aide de différents déclencheurs, conditions et actions.
- Pour en savoir plus sur les fonctionnalités avancées, consultez la documentation sur les API Home.
Bravo !