O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Adicionar novos dispositivos Matter a uma casa

As APIs do Google Home para iOS usam um hub Matter para comissionar um dispositivo em um fabric. Durante o comissionamento, o app envia um comando para o SDK e, em seguida, para o hub.

Configuração do projeto do Xcode

Implementado no app de exemplo para iOS

Antes de implementar a API Commissioning, adicione os recursos, as autorizações e as propriedades Info.plist necessárias aos destinos do Xcode:

Direitos

Inclua as seguintes entradas nos arquivos .entitlements do destino e da extensão do app principal:

Gerenciamento de credenciais da rede Thread:
```
<key>com.apple.developer.networking.manage-thread-network-credentials</key>
<true/>
```
Para usar esse direito em um build distribuído, envie um formulário de solicitação de direito à Apple. A Apple exige que você comprove sua participação no Thread Group e verifique se o Thread Border Router (TBR) é certificado pelo Thread Group.

Informações da rede Wi-Fi:

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

Grupos de apps: adicione um grupo de apps compartilhado para permitir que o app principal e a Matter extensão de adição de dispositivo se comuniquem (por exemplo, group.com.yourdomain.appgroupname). Esse identificador é criado e registrado pelo desenvolvedor no Apple Developer Console e precisa corresponder ao grupo de apps configurado nos recursos de destino no Xcode. O SDK do Google Home usa esse identificador em ambos os destinos para sincronizar automaticamente o estado de comissionamento, as credenciais do fabric e as listas de ambientes usando um contêiner UserDefaults compartilhado.

Compartilhamento de conjunto de chaves (opcional)

Se a extensão do app precisar recuperar credenciais ou tokens de acesso armazenados pelo app principal usando UserInfo.authorizationToken(), configure um grupo de acesso de conjunto de chaves compartilhado para os destinos do app principal e da extensão do app no plist de direitos:

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

Propriedades do Info.plist

Inclua as seguintes chaves de descrição no Info.plist do destino principal do app:

Descrição do uso da localização:

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

Serviços do Bonjour: Em NSBonjourServices, inclua os serviços necessários para a descoberta local de Matter e Thread:

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

Descrição do uso da rede local: inclua a chave NSLocalNetworkUsageDescription com uma mensagem explicando as permissões de descoberta de rede local.

Configurar um dispositivo

Para configurar um dispositivo Matter:

Notifique o Home APIs iOS SDK para se preparar para as solicitações de comissionamento do Matter com o structure.prepareForMatterCommissioning(). Esse comando vai:
- Verifique se a permissão foi concedida.
- Verifique se o hub está on-line e acessível.
- Verifique se não há outra sessão de comissionamento ativa em andamento.
```
do {
  try await structure.prepareForMatterCommissioning()
} catch {
  // Failed to prepare for Matter Commissioning
  return
}
```

Crie uma solicitação com MatterAddDeviceRequest() para iniciar o fluxo de suporte do Matter da Apple.

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

let request = MatterAddDeviceRequest(topology: topology)

Faça a solicitação com perform(). Se ocorrer um erro, cancele a solicitação de comissionamento com 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.
}

Crie um App Group ID no Console para desenvolvedores da Apple para permitir que o app se comunique com a extensão MatterAddDevice ao comissionar o dispositivo.

Você também precisará atualizar o identificador do pacote do aplicativo e os perfis de provisionamento para usar esse ID de grupo.

Ao inicializar, configure a instância Home para usar o identificador de grupo.

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

  return true
}

Implemente a extensão de app Matter para iOS da Apple.

O exemplo de código mostra como implementar uma subclasse da API MatterAddDeviceExtensionRequestHandler da Apple.

No mínimo, adicione o framework GoogleHomeMatterCommissionerSDK ao destino da extensão e substitua três métodos para chamar as APIs Google Home platformHomeMatterCommissioner.

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
    }
  }
}