Device Details UI BizBundle

Last Updated on : 2022-06-23 09:23:59download

Device Details UI BizBundle supports the following features:

Modify device information, such as the device icon, device name, and room.
Query device information, such as device ID, signal strength, and more.
Create or modify device groups. Starting SDK v3.25.0, Group Management UI BizBundle must be additionally integrated.
Configure backup Wi-Fi networks.
Notify users of devices getting offline.
Remove devices.

Integrate with the UI BizBundle

Add components

Add the components of the Device Details UI BizBundle to the Podfile and run the command pod update.

source "https://github.com/tuya/TuyaPublicSpecs.git"
source 'https://cdn.cocoapods.org/'

target 'your_target_name' do
  # TuyaSmartResidence SDK
  pod "TuyaSmartResidenceKit"
  # Adds the Device Details UI BizBundle.
  pod 'TuyaSmartResidenceDeviceDetailBizBundle'
end

Permissions

The UI BizBundle supports the upload of device icons. To implement this feature, the permissions on the system album and camera must be granted. This requires specific declarations of privacy and permissions from Apple. Add the following permission declaration to info.plist of your project:

<!-- Album -->
<key>NSPhotoLibraryUsageDescription</key>
<string>Authorizes the app to access the album of the mobile phone</string>
<!-- Camera -->
<key>NSCameraUsageDescription</key>
<string>Authorizes the app to access the camera of the mobile phone</string>

Configuration file

Create the configuration file configList.json in the main project. If the file already exists, skip the creation. configList.json includes the content similar to the following lines:
```
{
	"deviceDetail": [{"type": "header"}],
	"Other configuration page key":[xxxxx]
}
```

Add the following content to configList.json:

key: deviceDetail

value:

[
	{
		"type":"header"
	},
	{
		"type": "device_info"
	},
	{
		"type": "net_setting"
	},
	{
		"type":"section_off_line_warn"
	},
	{
		"type":"off_line_warn"
	},
	{
		"type":"section_other"
	},
	{
		"type":"group_edit_devices"
	},
	{
		"type":"group_create"
	},
	{
		"type":"help_and_feedback"
	},
	{
		"type":"check_device_network"
	},
	{
		"type":"check_firmware_update"
	},
	{
		"type":"empty",
		"height":16
	},
	{
		"type":"footer"
	}
]

Customize device details.

The sequence of the item parameter in the deviceDetail array determines the sequence in which each item is displayed on the device details page. If item is removed, the associated device feature will also be removed from the device details page.

Item of `deviceDetail`	Device feature
header	View and modify the device icon, device name, and location.
device_info	Display device information.
net_setting	Display backup Wi-Fi networks.
off_line_warn	Notify users of devices getting offline.
group_edit_devices	Modify a group.
group_create	Create a group.
footer	Remove devices.
section_other	This is a section header and serves no purpose.
empty	This is an empty `view` and serves no purpose.

Usage instruction

Things to note

Before the UI BizBundle is called, the following method must be implemented for the site:

[self.site fetchSiteDetailWithSuccess:^(TuyaResidenceSiteModel * _Nonnull siteModel) {
	
} failure:^(NSError *error) {

}];

Then, implement the protocol method currentFamilyId in TYFamilyProtocol.

#import <TuyaSmartBizCore/TuyaSmartBizCore.h>
#import <TYModuleServices/TYFamilyProtocol.h>

- (void)initCurrentSite {
	// Registers the protocol to be implemented.
	[[TuyaSmartBizCore sharedInstance] registerService:@protocol(TYFamilyProtocol) withInstance:self];
}

// Implements the protocol method.
- (long long)currentFamilyId {
	return @"site id";
}

Implement optional features

The features to create and modify groups are optional. To implement them, Group Management UI BizBundle must be additionally integrated.

Make API requests

Method	Parameter
Navigate to the network detection page	Device ID
Navigate to device details by means of Push	TuyaSmartDeviceModel/TuyaSmartGroupModel

#import <TuyaSmartBizCore/TuyaSmartBizCore.h>
#import <TYModuleServices/TuyaSmartResidenceDeviceDetailProtocol.h>

id<TuyaSmartResidenceDeviceDetailProtocol> impl = [[TuyaSmartBizCore sharedInstance] serviceOfProtocol:@protocol(TuyaSmartResidenceDeviceDetailProtocol)];

// Navigates to the page of network detection.
[impl gotoDeviceDetailNetworkViewControllerWithDeviceId:@"Device ID"];

// For devices
TuyaSmartDevice *device = [TuyaSmartDevice deviceWithDeviceId:@"Device ID"];
[impl gotoDetailViewControllerWithDevice:device.deviceModel group:nil];

// For groups
TuyaSmartGroup *group = [TuyaSmartDevice groupWithGroupId:@"Group ID"];
[impl gotoDetailViewControllerWithDevice:nil group:group.deviceModel];

Customize specific features

Specific features can be implemented with the configuration file configList.json. You can add the custom parameter type to deviceDetail in configList.json.

The value of type must start with c_. For example, c_test_insert and c_test_async_insert can be added.

{
	"deviceDetail": [
	 	{
			"type":"c_test_insert"
		},
		{
			"type":"c_test_async_insert"
		},
		{
			"type":"header"
		},
		{
			"type": "device_info"
		},
		{
			"type": "net_setting"
		},
		{
			"type":"section_off_line_warn"
		},
		{
			"type":"off_line_warn"
		},
		{
			"type":"section_other"
		},
		{
			"type":"help_and_feedback"
		},
		{
			"type":"check_device_network"
		},
		{
			"type":"check_firmware_update"
		},
		{
			"type":"empty",
			"height":16
		},
		{
			"type":"footer"
		}
	]
}

Return item data

Synchronous callback

/// Synchronize callbacks for item insertion
/// @param block Synchronous handling of item insertion callbacks
- (void)insertMenuItem:(ResidenceInsertMenuItemBlock)block;

//@param type type added by configList.json
//@param device device model
//@param group The group model. Determines if the device is a group or not, based on whether the group is nil
//@return An object that complies with the TuyaSmartResidenceDeviceDetailCustomMenuModel protocol. If nil is returned, the item of this type will not be displayed
typedef id<TuyaSmartResidenceDeviceDetailCustomMenuModel> _Nullable (^ResidenceInsertMenuItemBlock)(NSString *  _Nonnull type, TuyaSmartDeviceModel * _Nullable device, TuyaSmartGroupModel * _Nullable group);

Asynchronous callback

/// Asynchronous callback for item insertion
/// @param block Callback for asynchronous handling of item insertion
- (void)insertMenuItemAsync:(ResidenceInsertMenuItemAsyncBlock)block;

// Asynchronously process the item insertion, call complete() when the asynchronous operation is finished, call back the data to the device details and refresh the list. Determine if the device is a group or not based on whether the group is nil
typedef void (^ResidenceInsertMenuItemAsyncBlock)(NSString * _Nonnull type, TuyaSmartDeviceModel * _Nullable device, TuyaSmartGroupModel * _Nullable group, ResidenceInsertMenuItemComplete _Nonnull complete);

Example

Step 1: Create a `Model` class

// Customizes a class that adopts the protocol `TuyaSmartResidenceDeviceDetailCustomMenuModel`.
@interface CustomMenuModel : NSObject<TuyaSmartResidenceDeviceDetailCustomMenuModel>
/// The title.
@property (nonatomic,copy) NSString *title;
/// The subtitle.
@property (nonatomic,copy) NSString *detail;
@end

@implementation CustomMenuModel
@end

Step 2: Configure the callback block

id<TuyaSmartResidenceDeviceDetailProtocol> impl = [[TuyaSmartBizCore sharedInstance] serviceOfProtocol:@protocol(TuyaSmartResidenceDeviceDetailProtocol)];
[impl insertMenuItem:^ id<TuyaSmartResidenceDeviceDetailCustomMenuModel> (NSString * _Nonnull type, TuyaSmartDeviceModel * _Nonnull device, TuyaSmartGroupModel * _Nonnull group) {
	if ([type isEqualToString:@"c_test_insert"]) {
		CustomMenuModel *model = [CustomMenuModel new];
		if (group) { // If `group` is `nil`, device data is returned. Otherwise, group data is returned.
			model.title = type;
			model.detail = @"group";
		}
		else {
			model.title = type;
			model.detail = @"device";
		}
		return model;
	}
	return nil;
}];

[impl insertMenuItemAsync:^(NSString * _Nonnull type, TuyaSmartDeviceModel * _Nullable device, TuyaSmartGroupModel * _Nullable group, ResidenceInsertMenuItemComplete _Nonnull complete) {
	if ([type isEqualToString:@"c_test_async_insert"]) {
		// The time-consuming operation.
		dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(3 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
			CustomMenuModel *model = [CustomMenuModel new];
			if (group) { // If `group` is `nil`, device data is returned. Otherwise, group data is returned.
				model.title = type;
				model.detail = @"group";
			}
			else {
				model.title = type;
				model.detail = @"device";
			}
			complete(model);
		});
	}
}];

Insert handler of item tapping event

id<TuyaSmartResidenceDeviceDetailProtocol> impl = [[TuyaSmartBizCore sharedInstance] serviceOfProtocol:@protocol(TuyaSmartResidenceDeviceDetailProtocol)];
[impl clickMenuItem: ^(NSString * _Nonnull type, TuyaSmartDeviceModel * _Nullable device ,TuyaSmartGroupModel * _Nullable group) {
	NSLog(@"clickItem: type:%@",type);
}];