ScreenRecognitionController控制

版本变更

摘要

本接口描述了一套在可见即可说的场景下结合端设备指令实现的屏幕识别控制能力，根据下发的坐标值或者系统支持的keycode值实现指令的执行。该场景强依赖dialogRequestId，仅支持语音交互；在端上异步上传截屏时会基于dialogRequestId作为会话标识，同时，端上会基于dialogRequestId记录当前状态下设备所处的状态，如果指令下发时端上状态已发生变更，该指令将被丢弃；

SmartRecognitionState状态

launcher需要在本地保存是否『可见即可说』的功能状态，如果开关已打开，需要拉起SmartRecognition服务（APK）并上报SmartRecognitionState状态，云端基于此端状态来判断是否将请求打到screen recognition bot；

消息样例

"clientContext": [
  {
    "header": {
      "namespace": "ai.dueros.device_interface.screen_recognition_controller",
      "name": "SmartRecognitionState"
    },
    "payload": {
      "status": {{BOOLEAN}},
      "forgroundApp": {
        "packageName" : "{{STRING}}",
        "activityName" : "{{STRING}}",
        "versionName" : "{{STRING}}",
        "versionCode" : {{INT32}},
        "appName" : "{{STRING}}"
      }
    }
  }
]

Payload参数说明

• status
  • 端上是否开启了『可见即可说』的功能
• (optional) foregroundApp
  • 当前前台正在展示的app信息 注： 获取versionName，versionCode等信息时，端上会触发一次binder通信，建议端上实现时增加一些优化策略，减少binder通讯次数。
• foregroundApp.packageName
  • 应用包名
• foregroundApp.activityName
  • 当前页面名称
• foregroundApp.versionName
  • 应用版本名称
• foregroundApp.versionCode
  • 应用版本号
• foregroundApp.appName
  • 展现名称

CommandExecuteResult事件

用于云方案场景时，端上执行指令的情况上报，这里特指ai.dueros.device_interface.screen_recognition_controller下的指令，如InputTextAction，TapAction等，只有执行成功时才需要上报。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.screen_recognition_controller",
        "name": "CommandExecuteResult",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
        "isExecuted": {{BOOLEAN}},
        "reason": "{{STRING}}",
        "directives": ["{{ENUM}}"]
    }
}

Payload参数说明

• isExecuted
  • 指令是否执行成功 true or false
• (optional) reason
  • 指令执行失败的原因，执行成功时无需返回
• (optional) directives
  • 被执行的指令名称，这里特指ai.dueros.device_interface.screen_recognition_controller下的指令，如InputTextAction，TapAction；只有执行成功时才需要上报。

InputTextAction指令

通过语音对焦点所在的输入框直接输入文本信息，如果焦点不在输入框里，指令将被丢弃；

{
  "header":{
    "namespace" : "ai.dueros.device_interface.screen_recognition_controller",
    "name":"InputTextAction",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}"
  },
  "payload":{
    "text": "{{STRING}}",
    "display": "{{STRING}}" 
  }
}

Payload参数说明

• text
  • 输入的文本内容；
• display
  • 在执行指令时，同步到屏幕上的显示内容，应用层可基于此字段提供用户提示，已确定用户能够感知到指令的执行；

TapAction指令

点击指令(包括单击、双击、长按)，端上执行时需要基于给定的区域范围找到中心点坐标执行点击触发操作；

{
  "header":{
    "namespace" : "ai.dueros.device_interface.screen_recognition_controller",
    "name":"TapAction",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}"
  },
  "payload":{
    "location": {
      "top": {{INT}},
      "left": {{INT}},
      "width": {{INT}},
      "height": {{INT}}
    },
    "doubleTap": {{BOOLEAN}},
    "longClick":{{BOOLEAN}},
    "display": "{{STRING}}" 
  }
}

Payload参数说明

• location
  • 可点击的坐标范围，以下值都是屏幕的绝对值
• location.top
  • 范围起始顶点值
• location.left
  • 范围起始左侧值
• location.width
  • 宽度
• location.height
  • 高度
• (optional) doubleTap
  • 描述当前事件是否为双击事件；true表示 双击事件，false表示单击事件；
• (optional) longClick
  • 描述当前事件是否为长按事件；true表示 长按事件，false表示单击事件；
• display
  • 在执行指令时，同步到屏幕上的显示内容，应用层可基于此字段提供用户提示，已确定用户能够感知到指令的执行；

SwipeAction指令

滑动指令（左滑、右滑、上滑、下滑），滑动指令会下发一定的区间范围，端上会基于该区间范围内设置滑动起始点和终止点坐标；

{
  "header":{
    "namespace" : "ai.dueros.device_interface.screen_recognition_controller",
    "name":"SwipeAction",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}"
  },
  "payload":{
    "location": {
      "top": {{INT}},
      "left": {{INT}},
      "width": {{INT}},
      "height": {{INT}}
    },
    "duration": {{INT64}}, 
    "from" :{{CoordinateStructrue}},
    "to": {{CoordinateStructrue}},
    "display": "{{STRING}}"
  }
}

Payload参数说明

• location
  • 响应热区的坐标范围，以下值都是屏幕的绝对值
• location.top
  • 范围起始顶点值
• location.left
  • 范围起始左侧值
• location.width
  • 宽度
• location.height
  • 高度
• duration
  • 时间间隔 毫秒级，最大不超过500ms；默认建议值200ms；时间间隔和滑动长度有关，可自行基于效果调节；
• from
  • 起始坐标点
• to
  • 终止坐标点
• display
  • 在执行指令时，同步到屏幕上的显示内容，应用层可基于此字段提供用户提示，已确定用户能够感知到指令的执行；

CoordinateStructrue坐标结构体

{
    "x":{{INT}},
    "y":{{INT}}
}

• x
  • 水平坐标值
• y
  • 垂直坐标值

KeycodeControlAction指令

keycode控制指令

{
  "header":{
    "namespace" : "ai.dueros.device_interface.screen_recognition_controller",
    "name":"KeycodeControlAction",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}"
  },
  "payload":{
    "keycode": {{INT}},   
    "display": "{{STRING}}"
  }
}

Payload参数说明

• keycode
  • keycode的值
• display
  • 在执行指令时，同步到屏幕上的显示内容，应用层可基于此字段提供用户提示，已确定用户能够感知到指令的执行；

以Android系统提供的标准对照表为例，具体可支持的keycode如下表

基本

符号类

控制类

媒体控制类（暂未用到，可扩展到车机场景）