Scene Recommendation

Last Updated on : 2024-07-11 07:41:34download

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.

This API method is throttled every 12 hours. The matching logic will no longer be executed in the cloud within each throttling period if this API method is repeatedly called. This API method is only applicable to apps developed based on App SDK v3.29.0 or later.

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?) {
    
                    }
                })
    
  • For more information about the examples of App SDK versions earlier than v5.0.0, see History Version.

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?) {
    
                    }
                })
    
  • For more information about the examples of App SDK versions earlier than v5.0.0, see History Version.

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 throttled every 12 hours. The matching logic will no longer be executed in the cloud within each throttling period if this API method is repeatedly called. This API method is only applicable to apps developed based on App SDK v3.29.0 or later.

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?) {
    
                    }
                })
    
  • For more information about the examples of App SDK versions earlier than v5.0.0, see History Version.

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?) {
    
                    }
                })
    
  • For more information about the examples of App SDK versions earlier than v5.0.0, see History Version.

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.

After the scene is added, you must refresh the list of recommended scenes and effective scenes. The scene will not be recommended after it is added to the list of effective scenes. This API method is only applicable to apps developed based on App SDK v3.21.0 or later.

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?) {
    
                    }
                })
    
  • For more information about the examples of App SDK versions earlier than v5.0.0, see History Version.

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.

After the scene is removed, you must refresh the list of recommended scenes. The scene will no longer be recommended. This API method is only applicable to apps developed based on App SDK v3.21.0 or later.

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?) {
    
                    }
                })
    
  • For more information about the examples of App SDK versions earlier than v5.0.0, see History Version.