User management

User management

The user who created the home is the administrator of the home and can do everything from adding a guest user to the home. A ny user (HMUser) that an administrator adds to this home has a limited permission. Guests cannot change the layout of the home, but they can do the following:

• Identify smart appliances
• Read and write characteristics
• Observe changes in attribute values
• Execute the action set

For example, the head of a family can create a home layout and add family members to it. E ach family member must have an iOS device and Apple ID and the associated iCloud account. i Cloud requires an Apple ID entered by the individual to match the Apple ID provided by the head of household to allow them to access the home. Apple IDs are not visible to your app due to privacy concerns.

The administrator needs to follow these steps to add a guest to home:

1. The administrator calls an action to add the guest to the home.

2. Your app calls addUserWithCompletionHandler: Asynchronous method.

3. HomeKit displays a dialog box asking for the guest's Apple ID.

4. The user enters the guest's Apple ID.

5. A new user is returned in the completed callback.

6. Your app shows the guest's name.

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

1. Users enter iCloud credentials (Apple ID and password) in iCloud preferences.

2. The user launches your app.

3. Your app gets a home collection through home manager object.

4. If iCloud's credentials are the same as the Apple ID entered by the administrator, the administrator's home will appear in the home properties.

The operation performed by the guest may fail. If an HMErrorCodeInsufficient Privileges error code appears in an asynchronous method, this means that the user does not have sufficient permissions to perform the action - perhaps the user is a guest, not an administrator.

To test that your app is handling guest users correctly, read Testing Multiple iOS Devices and Users.

Add and remove users

To add a guest user to home, use 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 users from home, use the HMHome class's removeUser:endHandler: method.

Check newly added and removed users and update views by implementing the home:didAddUser:and home:didRemoveUser: protocol methods in the HMHomeDelegate protocol. For how to create a delegate, read Observing Changes to Individual Homes.

Get the user name

For privacy reasons, your app has only read access to the user name and cannot read or write the user's Apple ID. U se the users property of the HMHome object to get the user. Use the name property of the HMUser class to get the user name.