Scene Recommendation

Last Updated on : 2023-05-25 06:23:47

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 the latest matching scenes to recommend

API description

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

You do not need to call this API method prior to each request that is made to get a list of recommended scenes. You can set an interval to call this API method. For example, call it only once every 12 hours to refresh the matching scenes to recommend.

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

ObjC:

/// Returns a list of the latest matching scenes to recommend.
[ThingSmartSceneManager.sharedInstance updateMatchingRecommendWithHomeId:123456 success:^(id result) {

} failure:^(NSError *error) {

}];

Swift:

/// Returns a list of the latest matching scenes to recommend.
ThingSmartSceneManager.sharedInstance().updateMatchingRecommend(withHomeId: 123456) { (data) in

} failure: { (error) in

}

Get recommended scenes

API description

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

Parameters

Parameter	Description
homeId	The home ID.
success	The success callback. A scene list model is returned.
failure	The failure callback. An error message is returned.

Example

ObjC:

/// Returns a list of recommended scenes.
[ThingSmartSceneManager.sharedInstance getRecommendedSceneListWithHomeId:123456 success:^(NSArray<ThingSmartSceneModel *> *list) {

} failure:^(NSError *error) {

}];

Swift:

/// Returns a list of recommended scenes.
ThingSmartSceneManager.sharedInstance().getRecommendedSceneList(withHomeId: 123456) { (list) in

} failure: { (error) in

}

Get a list of the latest scenes matching a device

API description

Returns a 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 home ID.
successHandler	The success callback.
failureError	The failure callback.

Example

ObjC:

/// Returns the latest matching scenes that can be recommended to a device.
[ThingSmartSceneManager.sharedInstance updateMatchingDialogRecommendWithHomeId:123456 success:^(id result) {

} failure:^(NSError *error) {

}];

Swift:

/// Returns the latest matching scenes that can be recommended to a device.
ThingSmartSceneManager.sharedInstance().updateMatchingDialogRecommend(withHomeId: 123456) { data in

} failure: { error in

}

Get recommended scenes specific to a device

API description

Returns a list of scenes that are recommended to a device at the end of its pairing process.

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

Parameters

Parameter	Description
homeId	The home ID.
deviceId	The device ID.
count	The number of scenes that are recommended to the device. Maximum value: `4`.
success	The success callback. A scene model is returned.
failure	The failure callback. An error message is returned.

Example

ObjC:

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

} failure:^(NSError *error) {

}];

Swift:

/// Returns a list of scenes that are recommended to the specified device.
ThingSmartSceneManager.sharedInstance().getRecommendedSceneList(withHomeId: 123456, deviceId: "device id", count: 4) { list in

} failure: { error in

}

Get recommended scenes specific to devices

API description

Returns a list of scenes that are recommended to multiple devices for the current home in the same call. 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)getRecommendDeviceListWithDevIds:(NSArray<NSString *> *)devIds
                                  homeId:(long long)homeId
                                 success:(void (^)(NSDictionary<NSString *,ThingSmartSceneModel *> *dict))success
                                 failure:(ThingFailureError)failure;

Parameters

Parameter	Description
devIds	The list of device IDs. Up to 20 device IDs are supported in the same call.
homeId	The home ID.
success	The success callback. A scene dictionary model is returned. Only one recommended scene is returned for each device.
failure	The failure callback. An error message is returned.

Example

ObjC:

/// Returns a list of scenes that are recommended to the specified devices in the same call.
[ThingSmartSceneManager.sharedInstance getRecommendDeviceListWithDevIds:@[@"11", @"22"] homeId:123456 success:^(NSDictionary<NSString *,ThingSmartSceneModel *> *dict) {

} failure:^(NSError *error) {

}];

Swift:

/// Returns a list of scenes that are recommended to the specified devices in the same call.
ThingSmartSceneManager.sharedInstance().getRecommendDeviceList(withDevIds: ["11", "22"], homeId: 123456) { (dictionary) 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	Description
sceneId	The ID of the recommended scene.
homeId	The home ID.
success	The success callback. A scene model is returned.
failure	The failure callback. An error message is returned.

Example

ObjC:

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

} failure:^(NSError *error) {

}];

Swift:

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

} failure: { error in

}

Add a recommended scene

API description

Adds and saves a desired recommended scene to the list of effective scenes. After the scene is added, users can refresh the list of effective scenes to find it from the list.

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

Parameters

Parameter	Description
homeId	The home ID.
success	The success callback. A scene model is returned.
failure	The failure callback. An error message is returned.

Example

ObjC:

/// Adds 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:

/// Adds 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

Removes an undesired recommended scene from the list of recommended scenes.

To get the list of the latest recommended scenes, after this API method is called, wait five seconds and then pull the list of recommended scenes.

- (void)removeRecommendSceneWithHomeId:(long long)homeId
                               success:(ThingSuccessHandler)success
                               failure:(ThingFailureError)failure;

Parameters

Parameter	Description
homeId	The home ID.
success	The success callback.
failure	The failure callback. An error message is returned.

Example

ObjC:

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

} failure:^(NSError *error) {

}];

Swift:

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

}, failure: { error in

})
```error in

})

Prev DocSmart Scenes

Next DocExtension SDK