Scene Recommendation

Scene recommendation is designed to improve connections between users and smart devices through scene services and enhance smart scene capabilities for the devices. This topic describes API methods for scene recommendation to implement a range of features. For example, get a list of recommended scenes, get a list of recommended scenes for a specific device, get details of a recommended scene, and add or remove a recommended scene. For more information about scene recommendation, see Scene Recommendation Management.

Get recommended scenes

API description

- (void)getRecomSceneList:(long long)homeId
           recomListParam:(TSceneRecomListParams *)params
                  success:(void(^)(NSArray<ThingSmartSceneModel *> *list))success
                  failure:(ThingFailureError)failure;

Parameters

Parameter	Type	Description
homeId	long long	The ID of the current home.
params	TSceneRecomListParams object	The parameter object for scene recommendation.
success	block	The success callback, returning a scene list model.
failure	block	The failure callback, returning an error message.

Fields of TSceneRecomListParams

Parameter	Type	Description
TSceneRecomListSource	enum	The request source. TSceneRecomListSourceNormal: The common source.
size	int	The number of entries returned per page.
devId	string	The device ID.
shouldShowDidAddedRecommend	bool	Whether to show the recommended scene that has been added.

Example

Objective-C:

TSceneRecomListParams *recomListParams = [TSceneRecomListParams new];
recomListParams.source = TSceneRecomListSourceNormal;
recomListParams.size = 10;
recomListParams.shouldShowDidAddedRecommend = NO;

[[ThingSmartSceneManager sharedInstance] getRecomSceneList:123455 recomListParam:recomListParams success:^(NSArray<ThingSmartSceneModel *> * _Nonnull list) {

} failure:^(NSError *error) {

}];

Swift:

let recomListParams = TSceneRecomListParams.init();
recomListParams.source = .normal;
recomListParams.size = 10;
recomListParams.shouldShowDidAddedRecommend = false;

ThingSmartSceneManager.sharedInstance().getRecomSceneList(123455, recomListParam: recomListParams) { recommendModels in

} failure: { error in

}

Get recommended scenes for a device

API description

Get the list of recommended scenes when the device is paired.

- (void)getRecommendedSceneListWithHomeId:(long long)homeId
                                 deviceId:(NSString *)deviceId
                                    count:(NSInteger)count
                                  success:(void(^)(NSArray<ThingSmartSceneModel *> *list))success
                                  failure:(ThingFailureError)failure;

Parameters

Parameter	Parameter	Description
homeId	long long	The ID of the current home.
deviceId	string	The device ID.
count	int	The maximum number of recommended scenes. 3 or 4 is recommended.
success	block	The success callback, returning a scene model.
failure	block	The failure callback, returning an error message.

Example

Objective-C:

///  Get a list of recommended scenes for the device
[ThingSmartSceneManager.sharedInstance getRecommendedSceneListWithHomeId:123456 deviceId:@"device id" count:4 success:^(NSArray<ThingSmartSceneModel *> *list) {

} failure:^(NSError *error) {

}];

Swift:

///  Get a list of recommended scenes for the device
ThingSmartSceneManager.sharedInstance().getRecommendedSceneList(withHomeId: 123456, deviceId: "device id", count: 4) { list in

} failure: { error in

}

Get recommended scenes for multiple devices

API description

Get the list of recommended scenes for multiple devices in the current home in one go. Only one recommended scene is returned for each device.

This API method is only applicable to apps developed based on App SDK v3.33.5 or later.

- (void)fetchRecommendListForDeviceIDs:(NSArray<NSString *> *)deviceIDs
                                homeId:(long long)homeId
                               success:(void (^)(NSDictionary<NSString *,ThingSmartSceneModel *> *dict))success
                               failure:(ThingFailureError)failure;

Parameters

Parameter	Type	Description
deviceIDs	array	The list of device IDs. Up to 20 device IDs are supported in the same call.
homeId	long long	The ID of the current home.
success	block	The success callback, returning a scene dictionary model. Only one recommended scene is returned for each device.
failure	block	The failure callback, returning an error message.

Example

Objective-C:

/// Get a list of recommended scenes for multiple devices
[[ThingSmartSceneManager sharedInstance] fetchRecommendListForDeviceIDs:@[@"123", @"456"] homeId:789 success:^(NSDictionary<NSString *,ThingSmartSceneModel *> * _Nonnull dict) {

} failure:^(NSError *error) {

}];

Swift:

/// Get a list of recommended scenes for multiple devices
ThingSmartSceneManager.sharedInstance().fetchRecommendList(forDeviceIDs: ["123", "345"], homeId: 789) { recomendMap in

} failure: { error in

}

Get details of a recommended scene

API description

- (void)getRecommendSceneDetailWithSceneId:(NSString *)sceneId
                                    homeId:(long long)homeId
                                   success:(void (^)(ThingSmartSceneModel *sceneModel))success
                                   failure:(ThingFailureError)failure;

Parameters

Parameter	Parameter	Description
sceneId	string	The ID of the recommended scene.
homeId	long long	The ID of the current home.
success	block	The success callback, returning a scene model.
failure	block	The failure callback, returning an error message.

Example

Objective-C:

/// Get the details of the recommended scene 
[ThingSmartSceneManager.sharedInstance getRecommendSceneDetailWithSceneId:@"recommend id" homeId:123456 success:^(ThingSmartSceneModel *sceneModel) {

} failure:^(NSError *error) {

}];

Swift:

/// Get the details of the recommended scene
ThingSmartSceneManager.sharedInstance().getRecommendSceneDetail(withSceneId: "recommend id", homeId: 123456) { sceneModel in

} failure: { error in

}

Add a recommended scene

API description

Add a recommended scene to the list of existing scenes. After the scene is added, users can refresh the list of existing scenes to find it.

- (void)saveRecommendSceneWithHomeId:(long long)homeId
                             success:(void (^)(ThingSmartSceneModel *sceneModel))success
                             failure:(ThingFailureError)failure;

Parameters

Parameter	Type	Description
homeId	long long	The ID of the current home.
success	block	The success callback, returning a scene model.
failure	block	The failure callback, returning an error message.

Example

Objective-C:

/// Add a recommended scene
ThingSmartSceneModel *sceneModel = [[ThingSmartSceneModel alloc] init];
sceneModel.sceneId = @"123456";
ThingSmartScene *sceneService = [ThingSmartScene sceneWithSceneModel:sceneModel];
[sceneService saveRecommendSceneWithHomeId:123456 success:^(ThingSmartSceneModel *sceneModel) {

} failure:^(NSError *error) {

}];

Swift:

/// Add a recommended scene
let sceneModel = ThingSmartSceneModel.init()
sceneModel.sceneId = "123456"
let sceneService = ThingSmartScene.init(sceneModel: sceneModel)
sceneService?.saveRecommendScene(withHomeId: 123456, success: { sceneModel in

}, failure: { error in

})

Remove a recommended scene

API description

Remove an undesired recommended scene from the recommendation list.

- (void)unlikeRecommend:(long long)homeId
      recomHandleParams:(TSceneRecomHandleParams *)params
                success:(ThingSuccessBOOL)success
                failure:(ThingFailureError)failure;

Parameters

Parameter	Type	Description
homeId	long long	The ID of the current home.
params	TSceneRecomHandleParams object	Request parameters
success	block	The success callback.
failure	block	The failure callback, returning an error message.

TSceneRecomHandleParams object

Parameter	Type	Description
recomBizType	enum	See TSceneRecomBizType for the type of the recommended scene. TSceneRecomBizTypeUnknown: Unknown TSceneRecomBizTypeScene: Common TSceneRecomBizTypeEnergy: Energy usage TSceneRecomBizTypeWarning: Warning
recommendId	string	The ID of the recommended scene.
gid	string	The home ID.

Example

Objective-C:

TSceneRecomHandleParams *params = [TSceneRecomHandleParams new];
params.recommendId = self.sceneModel.sceneId;
params.recomBizType = self.sceneModel.bizType;
params.gid = [NSString stringWithFormat:@"%lld", homeId];

[[ThingSmartSceneManager sharedInstance] unlikeRecommend:homeId recomHandleParams:params success:^(BOOL result) {

} failure:^(NSError *error) {
}];

Swift:

let recomHandleParams = TSceneRecomHandleParams.init()
recomHandleParams.gid = ""
recomHandleParams.recomBizType = .energy
recomHandleParams.recommendId = ""
ThingSmartSceneManager.sharedInstance().unlikeRecommend(123456, recomHandleParams: recomHandleParams) { result in

} failure: { error in
    let errorMessage = error?.localizedDescription ?? ""
    SVProgressHUD.showError(withStatus: errorMessage)
}

(Deprecated) Get the latest matching recommended scenes

API description

Get the list of the latest scenes that match certain conditions before the scenes are recommended to users.

This API method is only applicable to apps developed based on App SDK v3.33.5 or later.

- (void)updateMatchingRecommendWithHomeId:(long long)homeId
                                  success:(ThingSuccessID)successHandler
                                  failure:(ThingFailureError)failureError;

Parameters

Parameter	Description
homeId	The home ID.
successHandler	The success callback.
failureError	The failure callback.

Example

Objective-C:

/// Match recommended scenes
[ThingSmartSceneManager.sharedInstance updateMatchingRecommendWithHomeId:123456 success:^(id result) {

} failure:^(NSError *error) {

}];

Swift:

/// Match recommended scenes
ThingSmartSceneManager.sharedInstance().updateMatchingRecommend(withHomeId: 123456) { (data) in

} failure: { (error) in

}

(Deprecated) Get the latest matching recommended scenes for a device

API description

Get the list of the latest matching scenes that can be recommended to a device at the end of the pairing process. This API method is called before the request that displays the recommended scenes for the device.

This API method is only applicable to apps developed based on App SDK v3.33.5 or later.

- (void)updateMatchingDialogRecommendWithHomeId:(long long)homeId
                                        success:(ThingSuccessID)successHandler
                                        failure:(ThingFailureError)failureError;

Parameter	Description
homeId	The ID of the current home.
successHandler	The success callback.
failureError	The failure callback.

Example

Objective-C:

/// Match the recommended scene for a device
[ThingSmartSceneManager.sharedInstance updateMatchingDialogRecommendWithHomeId:123456 success:^(id result) {

} failure:^(NSError *error) {

}];

Swift:

/// Match the recommended scene for a device
ThingSmartSceneManager.sharedInstance().updateMatchingDialogRecommend(withHomeId: 123456) { data in

} failure: { error in

}