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

API description

Returns a list of the latest scenes that match certain conditions before you call getRecommendAll that returns a list of recommended scenes.

fun requireRecommendMatch(relationId: Long, callback: IResultCallback<Boolean>?)

Parameters

Parameter	Description
relationId	The home ID.
callback	The callback.

Example

• For App SDK v5.0.0:

      ThingHomeSdk.getSceneServiceInstance().recommendService().requireRecommendMatch(
              relationId,
              object : IResultCallback<Boolean>() {
                  override fun onSuccess(result: Boolean) {
  
                  }
                  override fun onError(errorCode: String?, errorMessage: String?) {
  
                  }
              })
  

Get recommended scenes

API description

Returns a list of recommended scenes. Before this API method, you must call requireRecommendMatch that returns a list of the latest matching scenes. Otherwise, the recommended scenes in the response will be unchanged. This API method is only applicable to apps developed based on App SDK v3.21.0 or later.

fun getRecommendAll(relationId: Long, callback: IResultCallback<List<RecommendScene>?>?)

Parameters

Parameter	Description
relationId	The home ID.
callback	The callback.

The following table lists the properties of RecommendScene.

Field	Type	Description
id	Long	The ID of the recommended scene.
recommendId	String	The ID of the recommended scene.
matchType	Int	The rules of matching conditions. Valid values: 1: Scene actions are triggered when all conditions are met. 0: Scene actions are triggered when any of the conditions is met.
ownerId	String	The home ID.
name	String	The name of a specified scene.
coverIcon	String	The URL of the scene icon.
background	String	The background image.
displayColor	String	The background color of the displayed scene.
recomDescription	String	The description of the scene.
recomCoefficient	Int	The recommendation coefficient.
hotCount	String	The number of users who have accessed the recommended scene.
ruleGenre	Int	The type of linkage that triggers the scene.
conditions	List<SceneCondition>	The list of scene conditions.
actions	List<SceneAction>	The list of actions in the scene.

Example

• For App SDK v5.0.0:

      ThingHomeSdk.getSceneServiceInstance().recommendService().getRecommendAll(
              relationId,
              object : IResultCallback<List<RecommendScene>?>() {
                  override fun onSuccess(result: List<RecommendScene>?) {
  
                  }
                  override fun onError(errorCode: String?, errorMessage: String?) {
  
                  }
              })
  

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.

fun requireRecommendMatchTwo(relationId: Long, callback: IResultCallback<Boolean>?)

Parameters

Parameter	Description
relationId	The home ID.
callback	The callback.

Example

• For App SDK v5.0.0:

      ThingHomeSdk.getSceneServiceInstance().recommendService().requireRecommendMatchTwo(
              relationId,
              object : IResultCallback<Boolean>() {
                  override fun onSuccess(result: Boolean) {
  
                  }
                  override fun onError(errorCode: String?, errorMessage: String?) {
  
                  }
              })
  

Get recommended scenes specific to a device

API description

Returns a list of scenes that are recommended to a specific device. Before this API method, you must call requireRecommendMatchTwo that returns a list of the latest scenes matching the device. Otherwise, the recommended scenes in the response will be unchanged. This API method is only applicable to apps developed based on App SDK v3.29.0 or later.

fun getRecommendsByDevice(
    relationId: Long,
    deviceId: String,
    size: Int,
    callback: IResultCallback<List<RecommendScene>?>?
)

Parameters

Parameter	Description
relationId	The home ID.
deviceId	The device ID.
size	The number of recommended scenes. For more information, see Scene Recommendation Rules.
callback	The callback.

Example

• For App SDK v5.0.0:

      ThingHomeSdk.getSceneServiceInstance().recommendService().getRecommendsByDevice(
              relationId, devId, 3,
              object : IResultCallback<List<RecommendScene>?>() {
                  override fun onSuccess(result: List<RecommendScene>?) {
  
                  }
                  override fun onError(errorCode: String?, errorMessage: String?) {
  
                  }
              })
  

Get recommended scenes specific to devices

API description

Returns a list of scenes that are recommended to multiple devices in the same call. This API method is only applicable to apps developed based on App SDK v3.34.5 or later.

fun requestRecommendSceneWithDeviceIds(
    relationId: Long,
    devIds: String,
    source: Int,
    callback: IResultCallback<ArrayList<RecommendPlainScene?>?>
)

Parameters

Parameter	Description
relationId	The home ID.
devIds	The list of device IDs, separated with commas (,). Example: "6cda1ca75a5a768f5czn9i,6cda1ca75a5a768f5czn9b"
source	1: The recommended scenes are retrieved from the device list. 2: The recommended scenes are retrieved from the device setting page. This value is currently unavailable.
callback	The callback.

Example

      ThingHomeSdk.getSceneServiceInstance().recommendService().requestRecommendSceneWithDeviceIds(relationId, devIds, 1,
            object : IResultCallback<ArrayList<RecommendPlainScene?>?> {
                override fun onSuccess(result: ArrayList<RecommendPlainScene?>?) {

                }

                override fun onError(errorCode: String?, errorMessage: String?) {

                }
    })

Get details of a recommended scene

API description

Returns details of a recommended scene. This API method is only applicable to apps developed based on App SDK v3.34.5 or later.

fun requestRecommendDetail(relationId: Long, sceneId: String, callback: IResultCallback<RecommendScene?>?)

Parameters

Parameter	Description
relationId	The home ID.
sceneId	The scene ID. It is equivalent to the recommendId field of RecommendScene.
callback	The callback.

Example

      ThingHomeSdk.getSceneServiceInstance().recommendService().requestRecommendDetail(
            relationId, recommendId,
            object : IResultCallback<RecommendScene?>() {
                override fun onSuccess(result: RecommendScene?) {

                }
                override fun onError(errorCode: String?, errorMessage: String?) {

                }
            })

Add a recommended scene

API description

Adds a recommended scene on the scene details page to save the scene as an effective one.

fun handleRecommend(
        relationId: Long,
        sceneId: String,
        action: String,
        sceneData: NormalScene?,
        callback: IResultCallback<Boolean?>?
    )

Parameters

Parameter	Description
relationId	The home ID.
sceneId	The scene ID. It is equivalent to the recommendId field of RecommendScene.
action	The action to add or save the recommended scene.
sceneData	The scene data in the edit area.
callback	The callback.

Example

• For App SDK v5.0.0:

      ThingHomeSdk.getSceneServiceInstance().recommendService().handleRecommend(
              relationId, sceneId, "save", normalScene,
              object : IResultCallback<Boolean?>() {
                  override fun onSuccess(result: Boolean?) {
  
                  }
                  override fun onError(errorCode: String?, errorMessage: String?) {
  
                  }
              })
  

Remove a recommended scene

API description

Removes an undesired recommended scene from the scene details page. Then, the scene disappears from the list of recommended scenes.

fun handleRecommend(
        relationId: Long,
        sceneId: String,
        action: String,
        sceneData: NormalScene?,
        callback: IResultCallback<Boolean?>?
    )

Parameters

Parameter	Description
relationId	The home ID.
sceneId	The scene ID. It is equivalent to the recommendId field of RecommendScene.
action	The action to remove or cancel the recommended scene.
sceneData	The scene data in the edit area. You can pass in null.
callback	The callback.

Example

• For App SDK v5.0.0:

      ThingHomeSdk.getSceneServiceInstance().recommendService().handleRecommend(
              relationId, sceneId, "remove", null,
              object : IResultCallback<Boolean?>() {
                  override fun onSuccess(result: Boolean?) {
  
                  }
                  override fun onError(errorCode: String?, errorMessage: String?) {
  
                  }
              })