Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Ajouter de nouveaux appareils Matter à une maison

Les API Home pour iOS utilisent un Matter hub pour mettre en service un appareil sur un réseau. Lors de la mise en service, l'application envoie une commande au SDK, puis au hub.

Configuration du projet Xcode

Avant d'implémenter l'API Commissioning, assurez-vous d'ajouter les fonctionnalités, les droits et les propriétés Info.plist requis à vos cibles Xcode :

Droits

Incluez les entrées suivantes dans les fichiers .entitlements de votre cible d'application principale et de votre extension :

Gestion des identifiants du réseau Thread :
```
<key>com.apple.developer.networking.manage-thread-network-credentials</key>
<true/>
```
Pour utiliser ce droit dans une version distribuée, vous devez envoyer un formulaire de demande de droit à Apple. Apple exige que vous prouviez votre appartenance au Thread Group et que vous vérifiiez que votre Thread Border Router (TBR) est certifié par le Thread Group.

Informations sur le Wi-Fi :

<key>com.apple.developer.networking.wifi-info</key>
<true/>

Groupes d'applications : ajoutez un groupe d'applications partagé pour permettre à votre application principale et à l'extension Matter Add Device de communiquer (par exemple, group.com.yourdomain.appgroupname). Cet identifiant est créé et enregistré par le développeur dans sa console de développement Apple. Il doit correspondre au groupe d'applications configuré dans les fonctionnalités cibles d'Xcode. Le SDK Google Home utilise cet identifiant dans les deux cibles pour synchroniser automatiquement l'état de mise en service, les identifiants de réseau et les listes de pièces à l'aide d'un conteneur UserDefaults partagé.

Partage du trousseau (facultatif)

Si l'extension de votre application doit récupérer des identifiants ou des jetons d'accès stockés par l'application principale à l'aide de UserInfo.authorizationToken(), vous devez configurer un groupe d'accès au trousseau partagé pour les cibles de votre application principale et de l'extension de votre application dans leur fichier plist de droits :

<key>keychain-access-groups</key>
<array>
    <string>$(AppIdentifierPrefix)your.shared.keychain.group</string>
</array>

Propriétés Info.plist

Incluez les clés de description suivantes dans le fichier Info.plist de la cible de votre application principale :

Description de l'utilisation de la position :

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your custom message explaining why location access is needed to read the current Wi-Fi SSID</string>

Services Bonjour : sous NSBonjourServices, incluez les services requis pour la détection locale de Matter et de Thread :

<key>NSBonjourServices</key>
<array>
    <string>_matter._tcp</string>
    <string>_matterc._udp</string>
    <string>_matterd._udp</string>
    <string>_meshcop._udp</string>
</array>

Description de l'utilisation du réseau local : incluez la clé NSLocalNetworkUsageDescription avec un message expliquant les autorisations de détection du réseau local.

Mettre en service un appareil

Pour mettre en service un appareil Matter :

Avertissez le Home APIs iOS SDK de se préparer aux Matter requêtes de mise en service avec structure.prepareForMatterCommissioning(). Cette commande effectue les opérations suivantes :
- Vérifie que l'autorisation a été accordée.
- S'assure que le hub est en ligne et accessible.
- Vérifie qu'aucune autre session de mise en service n'est en cours.
```
do {
  try await structure.prepareForMatterCommissioning()
} catch {
  // Failed to prepare for Matter Commissioning
  return
}
```

Créez une requête avec MatterAddDeviceRequest() pour démarrer le flux de prise en charge Matter d'Apple.

let topology = MatterAddDeviceRequest.Topology(
  ecosystemName: "Google Home",
  homes: [MatterAddDeviceRequest.Home(displayName: structure.name)]
)

let request = MatterAddDeviceRequest(topology: topology)

Exécutez la requête avec perform(). Si une erreur se produit, annulez la requête de mise en service avec structure.cancelMatterCommissioning().

do {
  // Starting MatterAddDeviceRequest.
  try await request.perform()
  // Successfully completed MatterAddDeviceRequest.
  let commissionedDeviceIDs = try structure.completeMatterCommissioning()
  // Commissioned device IDs.
} catch let error {
  structure.cancelMatterCommissioning()
  // Failed to complete MatterAddDeviceRequest.
}

Créez un App Group ID dans la console de développement Apple pour permettre à l'application de communiquer avec l'extension MatterAddDevice lors de la mise en service de l'appareil.

Vous devrez également mettre à jour l'identifiant de votre app bundle et vos profils de provisionnement pour utiliser cet ID de groupe.

Lors de l'initialisation, configurez l'instance Home pour qu'elle utilise l'identifiant de groupe.

func application(_ application: UIApplication, didFinishLaunchingWithOptions
launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
  Home.configure {
    $0.sharedAppGroup = "group.com.sample.app.commissioning"
  }

  return true
}

Implémentez l'extension d'application iOS Matter d'Apple.

L'exemple de code montre comment implémenter une sous-classe de l'API d'Apple MatterAddDeviceExtensionRequestHandler.

Au minimum, ajoutez le GoogleHomeMatterCommissionerSDK Framework à la cible de l'extension et remplacez trois méthodes pour appeler les Google Home platformHomeMatterCommissioner API.

commissionDevice
rooms
configureDevice

import MatterSupport
import GoogleHomeSDK
import OSLog

final class RequestHandler: MatterAddDeviceExtensionRequestHandler {
  // The App Group ID defined by the application to share information between the extension and main app.
  private static var appGroup = "group.com.sample.app.commissioning"

  ...

  // MARK: - Home API commissioning handlers

  /// Commissions a device to the Google Home ecosystem.
  /// - Parameters:
  ///   - home: The home that the device will be added to
  ///   - onboardingPayload: The payload to be sent to the Matter Commissioning SDK to commission the device.
  ///   - commissioningID: An identifier not used by the Home API SDK.
  override func commissionDevice(in home: MatterAddDeviceRequest.Home?, onboardingPayload: String, commissioningID: UUID) async throws {
    // Commission Matter device with payload.

    var onboardingPayloadForHub = onboardingPayload
    let homeMatterCommissioner = try HomeMatterCommissioner(appGroup: RequestHandler.appGroup)
    try await homeMatterCommissioner.commissionMatterDevice(
    onboardingPayload: onboardingPayloadForHub)
  }

  /// Obtains rooms from the Home Ecosystem to present to the user during the commissioning flow.
  /// - Parameter home: The home that the device will be added to.
  /// - Returns: A list of rooms if obtained from the Google Home ecosystem or an empty list if there was an error in getting them.
  override func rooms(in home: MatterAddDeviceRequest.Home?) async -> [MatterAddDeviceRequest.Room] {
    do {
      let homeMatterCommissioner = try HomeMatterCommissioner(appGroup: RequestHandler.appGroup)
      let fetchedRooms = try homeMatterCommissioner.fetchRooms()
      // Returning fetched rooms.
      return fetchedRooms
    } catch {
      // Failed to fetch rooms with error
      return []
    }
  }

  /// Pushes the device's configurations to the Google Home Ecosystem.
  /// - Parameters:
  ///   - name: The friendly name the user chose to set on the device.
  ///   - room: The room identifier that the user chose to put the device in.
  override func configureDevice(named name: String, in room: MatterAddDeviceRequest.Room?) async {
    // Configure Device name: room
    do {
      let homeMatterCommissioner = try HomeMatterCommissioner(appGroup: RequestHandler.appGroup)
      await homeMatterCommissioner.configureMatterDevice(
        deviceName: name, roomName: room?.displayName)
    } catch {
      // Configure Device failed with error
    }
  }
}