Managing Users

The user who creates a home is the admin for the home and can perform all operations including adding guest users to a home. Any user (HMUser) that an admin adds to a home has restricted privileges. Guests can’t modify the home layout in any way but can perform these types of actions:

For example, the head of a household creates a home layout and adds family members to the home. Each family member must have a personal iOS device and Apple ID with an associated iCloud account. The iCloud credentials that family members enter on their iOS devices must match the Apple ID provided by the head of a household in order for them to access the home. For privacy reasons, the Apple ID is hidden from your app.

Adding a guest to a home requires the following actions on the admin’s iOS device:

  1. The admin user invokes an action to add a guest to a home.

  2. Your app invokes the addUserWithCompletionHandler: asynchronous method.

  3. HomeKit displays a dialog requesting the guest’s Apple ID.

  4. The user enters the guest’s Apple ID in the dialog.

  5. The completion handler returns the new user object.

  6. Your app displays the guest’s name.

Adding a guest to a home requires the following actions on the guest’s iOS device:

  1. The user enters the user’s iCloud credentials (the Apple ID and password) in iCloud preferences.

  2. The user launches your app.

  3. Your app gets the collection of homes from the home manager object.

  4. If the iCloud credentials match the Apple ID entered by the admin, the admin’s home appears in the homes property.

Some operations performed by a guest may fail. If an asynchronous message to HomeKit fails with error code HMErrorCodeInsufficientPrivileges, the user is not allowed to perform the action—the user is probably a guest, not the admin.

To test whether your app handles guest users correctly, read Testing Multiple iOS Devices and Users.

Adding and Removing Users

To add a guest user to a home, use the addUserWithCompletionHandler: asynchronous method.

[self.home addUserWithCompletionHandler:^(HMUser *user, NSError *error) {
    if (error == nil) {
        // Successfully added a user
    }
    else {
       // Unable to add a user
    }
}];

To remove a user from a home, use the removeUser:completionHandler: method in the HMHome class.

Implement the home:didAddUser: and home:didRemoveUser: delegate methods in the HMHomeDelegate protocol to update views when other apps add and remove users. To create a home delegate, read Observing Changes to Individual Homes.

Getting User Names

For privacy reasons, your app has read-only access to the name of a user, not read or write access to the Apple ID of a user. Use the users property in the HMHome class to get the users of a home. Use the name property of the HMUser class to get the name of a user.