Initialize the home

bookmark_border Stay organized with collections Save and categorize content based on your preferences.

Before using any of the Home APIs for iOS, you must initialize the home in your app.

Home is the top-level entry to the SDK and provides access to all entities in the user's structure.

When requesting all entities of a particular type, the API returns a Query object that lets you choose how to receive the results.

Create a Home object

Use connect() to create a Home object. This is a basic step to access a user's home:

do {
  self.home = try await Home.connect()
} catch {
  Logger.error("Auth error: \(error).")
}

This call prompts the SDK to check authorization state. If unauthenticated, the SDK presents the OAuth flow for a user to grant permission to their home to the app.

Once you have access to a home, you can use the following APIs:

• Device & Structure APIs
• Commissioning API

Home configuration

When initialized, the Home client reads from an app provided HomeClientConfiguration object to prepare its environment. This object should be passed to the client prior to any Home API calls so that the permissions, automations, and commissioning features are able to interact with one's smart home project.

• teamID: The Apple Team ID of the app using SDK.
• clientID: The OAuth Client ID of the app using SDK. See Set up OAuth for your iOS app for more information.

• sharedAppGroup: The App Group used for shared storage with the Google Home Matter Commissioning SDK.

• strictOperationValidation: Validates if a trait or command is supported.

  • If true, you will receive an exception message if your trait or command is unsupported.
  • If false, a command or attribute write will still be sent, but you will receive an error for the unsupported trait.

• referencedAutomationTypes: The list of traits and device types you intend to use with the Automation API.

These options are set using the configure() method of the Home object as shown:

Home.configure {
  // Authentication and Home API usage configurations
  $0.teamID = "ABC123"
  $0.clientID = "123-abc.apps.googleusercontent.com"
  $0.strictOperationValidation = true
  // Commissioning configurations
  $0.sharedAppGroup = "group.com.company.commissioning"
  // Automation configurations
  $0.referencedAutomationTypes = ReferencedAutomationTypes(
    deviceTypes: [
        OnOffLightDeviceType.self,
        TemperatureSensorDeviceType.self,
        WindowCoveringDeviceType.self,
    ],
    traits: [
        Google.TimeTrait.self,
        Matter.OnOffTrait.self,
        Matter.TemperatureMeasurementTrait.self,
        Matter.WindowCoveringTrait.self,
    ]
  )
}

Permissions

Before using any of the Home APIs for iOS, the app must have permission to access devices or structures. The connect() process will prompt the SDK to check authorization state, and if unauthorized, will present the OAuth flow for granting permission.

Update permissions

To update permissions granted to the Home APIs, use presentPermissionsUpdate():

self.home?.presentPermissionsUpdate()

If the active user is signed into Safari, the permissions view will be presented for that user. Otherwise, the user will be prompted to select an account or sign in.

OkGoogle permissions

The okGoogle command is a device-level command and can be used to automate any device in the structure. However, a Home APIs app may not have access to every device. The following table describes how permissions are enforced in such cases.

Revoke access

For revoking access, use disconnect() to disconnect the Home object from the account:

await self.home?.disconnect()
self.home = nil