Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Dodawanie nowych urządzeń Matter do domu

Interfejsy API Google Home na iOS używają centrali Matter do dodawania urządzenia do sieci. Podczas uruchamiania aplikacja wysyła polecenie do pakietu SDK, a następnie do huba.

Konfiguracja projektu Xcode

Zaimplementowano w przykładowej aplikacji na iOS

Zanim wdrożysz interfejs Commissioning API, dodaj do celów Xcode wymagane funkcje, uprawnienia i właściwości Info.plist:

Zezwolenia

Uwzględnij te wpisy w plikach .entitlements głównego celu aplikacji i rozszerzenia:

Zarządzanie danymi logowania do sieci Thread:
```
<key>com.apple.developer.networking.manage-thread-network-credentials</key>
<true/>
```
Aby używać tego uprawnienia w kompilacji rozproszonej, musisz przesłać do Apple formularz prośby o uprawnienia. Firma Apple wymaga potwierdzenia członkostwa w Thread Group i potwierdzenia, że Thread Border Router (TBR) ma certyfikat Thread Group.

Dane sieci Wi-Fi:

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

Grupy aplikacji: dodaj udostępnioną grupę aplikacji, aby umożliwić komunikację między aplikacją główną a rozszerzeniem Matter Add Device Extension (np. group.com.yourdomain.appgroupname). Ten identyfikator jest tworzony i rejestrowany przez dewelopera w Apple Developer Console i musi być zgodny z grupą aplikacji skonfigurowaną w funkcjach docelowych w Xcode. Pakiet SDK Google Home używa tego identyfikatora w obu miejscach docelowych, aby automatycznie synchronizować stan uruchamiania, dane uwierzytelniające sieci Fabric i listy pomieszczeń za pomocą udostępnionego kontenera UserDefaults.

Udostępnianie pęku kluczy (opcjonalnie)

Jeśli rozszerzenie aplikacji musi pobrać dane logowania lub tokeny dostępu przechowywane przez aplikację główną za pomocą UserInfo.authorizationToken(), musisz skonfigurować udostępnioną grupę dostępu do pęku kluczy zarówno dla aplikacji głównej, jak i rozszerzenia aplikacji w pliku plist uprawnień:

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

Właściwości pliku Info.plist

W głównym celu aplikacji Info.plist uwzględnij te klucze opisu:

Opis użycia lokalizacji:

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

Usługi Bonjour: W sekcji NSBonjourServices uwzględnij usługi wymagane do wykrywania lokalnego Matter i Thread:

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

Opis wykorzystania sieci lokalnej: dodaj klucz NSLocalNetworkUsageDescription z wiadomością wyjaśniającą uprawnienia do wykrywania sieci lokalnej.

Konfigurowanie urządzenia

Aby skonfigurować urządzenie Matter:

Powiadom Home APIs iOS SDK, aby przygotować się na prośby o uruchomienie Matter z structure.prepareForMatterCommissioning(). To polecenie wykona następujące działania:
- Sprawdź, czy uprawnienia zostały przyznane.
- Upewnij się, że hub jest online i dostępny.
- Upewnij się, że nie trwa żadna inna aktywna sesja uruchamiania.
```
do {
  try await structure.prepareForMatterCommissioning()
} catch {
  // Failed to prepare for Matter Commissioning
  return
}
```

Utwórz prośbę za pomocą MatterAddDeviceRequest(), aby rozpocząć proces pomocy Matter Apple.

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

let request = MatterAddDeviceRequest(topology: topology)

Wykonaj żądanie za pomocą perform(). Jeśli wystąpi błąd, anuluj prośbę o uruchomienie za pomocą polecenia 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.
}

Utwórz App Group ID w konsoli programisty Apple, aby umożliwić aplikacji komunikację z rozszerzeniem MatterAddDevice podczas uruchamiania urządzenia.

Aby używać tego identyfikatora grupy, musisz też zaktualizować identyfikator pakietu aplikacji i profile obsługi administracyjnej.

Podczas inicjowania skonfiguruj instancję Home tak, aby używała identyfikatora grupy.

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

  return true
}

Zaimplementuj rozszerzenie aplikacji Matter na iOS od Apple.

Przykładowy kod pokazuje, jak zaimplementować podklasę interfejsu MatterAddDeviceExtensionRequestHandler API firmy Apple.

Dodaj co najmniej platformę GoogleHomeMatterCommissionerSDK do celu rozszerzenia i zastąp 3 metody, aby wywołać interfejsy API Google Home platform (GHP)HomeMatterCommissioner.

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