指令交互组件
更新时间：2020-07-07
端云交互指令组件整体介绍
用户通过机器人输入语音、文字、图像等信息后，SDK将输入的信息包装成事件（event）发送给服务器，并接收服务器返回的指令（directive）集，开发者通过传入指令监听回调接口的实现来接收指令集，进行对应的逻辑处理。
- 指令和事件是完成机器人与人交互的最基本的要素，设备端上发生的变化都通过上报相应的事件来通知服务端，服务端通过下发指令给设备端，对用户请求进行响应。
事件（event）
是设备端上报给服务端，通知服务端在设备端发生的事情。比如语音识别到用户说的话，人脸功能检测到人脸等。
指令（directive）
是服务端下发给设备端，设备端需要执行的操作。比如根据语音识别到的用户语义下发相关的语义指令或图文信息，根据人脸识别的图片信息下发人脸图片对应的用户信息等。
指令监听回调接口分类
- IDirectiveCallback 指令回调基础接口，用于接收服务端下发的原始json指令信息，用户可以基于原始指令信息开发业务功能。
- IDirectiveListener 指令监听扩展接口，在指令回调基础接口上，对指令数据进行了分类，简化原始json指令信息解析，每个分类定义了对应的接口，方便用户快速实现业务功能。指令监听扩展接口开源代码可在SampleApp中查找修改。
组件配置
指令组件作为SDK基础组件功能，在SDK初始化时会默认一起完成指令组件的配置对象创建和组件初始化。
获取配置对象
DirectiveModuleConfig directiveModuleConfig = new DirectiveModuleConfig();配置组件
// 私有化部署环境时，可以设置指令上传的服务端中转地址
directiveModuleConfig.robotRequestHostUrl = "http://172.0.0.1:8080/";指令回调基础接口
通过实现IDirectiveCallback指令监听回调接口，进行对指令数据回调的监听。
/**
* 指令回调基础接口
*/
public interface IDirectiveCallback {
/**
* 服务端指令下发接口
*
* @param directiveStatusCode 指令状态码
* @param directiveStatusMsg 指令状态信息
* @param directiveModel 指令数据对象
*/
void onDirectiveReceived(int directiveStatusCode,
String directiveStatusMsg,
DirectiveModel directiveModel);
}指令数据对象
public class DirectiveModel {
// 请求数据：指令命名空间
public String requestNamespace = "";
// 请求数据：指令名称
public String requestName = "";
// 请求数据：指令信息ID
public String requestMessageId = "";
// 请求数据：指令交互ID用于维护多轮对话
public String requestInteractionId = "";
// 返回数据：指令请求状态码
public int responseStatusCode = 0;
// 返回数据：指令请求状态信息
public String responseStatusMsg = "";
// 返回数据：指令返回原数据json格式
public String responseDirectives = "";
// 返回数据：指令返回图片数据
public byte[] responseByteData = null;
}指令监听扩展接口
目前SDK内置的IDirectiveListener接口如下图：
如图，目前共有七种IDirectiveListener的实现。
开发者需要在SDK中注册自己相应的IDirectiveListener来获取SDK的指令回调，步骤如下：
- 开发者编写
IDirectiveListener的接口实现类 - 通过
RobotSDKManager的addDirectiveListeners方法传入IDirectiveListener实现类到SDK中 - 当接口对应事件触发时，在
IDirectiveListener的回调方法中获得对应数据并实现相应业务逻辑
可以通过以下代码片段来理解这段过程：
// 1. 实现 IDirective 的接口实现类，此处以 IDialogListener 为例
IDialogListener mDialogListener = new IDialogListener() {
@Override
public void onVoiceOutput(String content) {
// 处理语音回复播放相关逻辑
}
@Override
public void onTextOutput(String content) {
// 处理文字对话显示相关逻辑
}
@Override
public void onHints(List <string> hints) {
// 处理提示文案显示相关逻辑
}
@Override
public void onEnd() {
// 对话结束相关逻辑
}
}；
......
// 2. 将接口实现类传入 SDK
RobotSDKManager.getInstance().addDirectiveListener(NamespaceGroup.DIALOG, mDialogListener);各个Listener说明如下：
IDialogListener
IDialogListener ：对话相关指令监听器
public interface IDialogListener extends IDirectiveListener {
/**
* 语音播报指令
* @param content 需要播报的语音内容
*/
void onVoiceOutput(String content);
/**
* 文字回复展示指令
* @param content 回复用户的对话内容
*/
void onTextOutput(String content);
/**
* 提示文本展示指令
* @param hints 需要展示的提示文本 List
*/
void onHints(List <string> hints);
/**
* 对话结束指令
* 当用户说出对话结束关键字（例如"再见"、"拜拜"）时触发回调
*/
void onEnd();
}IScreenListener
IScreenListener - 屏幕内容展示相关指令
public interface IScreenListener extends IDirectiveListener {
/**
* 文本卡片展示指令
* @param card 文本类型卡片 model
*/
void onRenderTextCard(TextCard card);
/**
* 图片卡片展示指令
* @param card 图片卡片 model
*/
void onRenderImageCard(ImageCard card);
/**
* 普通列表卡片展示指令
* @param listCard 普通列表卡片 model
*/
void onRenderNormalList(ListCard <normalcarditem> listCard);
/**
* 图片列表卡片展示指令
* @param listCard 图片列表卡片 model
*/
void onRenderSimpleImgList(ListCard<simpleimagecarditem> listCard);
/**
* 视频列表卡片展示指令
* @param listCard 视频列表卡片 model
*/
void onRenderVideoList(ListCard<videocarditem> listCard);
/**
* 用户卡片展示指令
* @param card 用户卡片 model
* @param data 用户照片的二进制数据
*/
void onRenderPerson(UserCard card, byte[] data);
/**
* 天气卡片展示指令
* @param card 天气卡片 model
*/
void onRenderWeather(WeatherInfoCard card);
/**
* 表情展示指令
* @param expression 表情关键字，例如 Sad、Happy
*/
void onRenderExpression(String expression);
}IActionListener
IActionListener - 动作控制指令
public interface IActionListener extends IDirectiveListener {
/**
* 行走指令
* @param direction 行走方向
* @param distance 行走距离
* @param distanceUnit 距离单位
*/
void onWalk(String direction, String distance, String distanceUnit);
/**
* 转向指令
* @param direction 转向方向
* @param angle 转向角度
* @param angleUnit 角度单位
*/
void onTurn(String direction, String angle, String angleUnit);
/**
* 举手指令
* @param hands hand字段可为以下内容：hand, right_hand, left_hand, double_hand
*/
void onRaiseHands(String hands);
/**
* 巡航指令
* @param switchStatus 状态开关
*/
void onCruise(String switchStatus);
/**
* 充电指令
* @param switchStatus 状态开关
*/
void onCharge(String switchStatus);
/**
* 握手指令
*/
void onShakeHands();
/**
* 拥抱指令
*/
void onHug();
/**
* 摇头指令
*/
void onTwistHead();
/**
* 向左看指令
*/
void onTurnHeadLeft();
/**
* 向右看指令
*/
void onTurnHeadRight();
/**
* 停止运动指令
*/
void onStop();
/**
* 打招呼指令
*/
void onWave();
/**
* 动一下指令
*/
void onDoAnAction();
}ISpeakerControllerListener
ISpeakerControllerListener - 扬声器控制指令
public interface ISpeakerControllerListener extends IDirectiveListener {
/**
* 静音指令
*/
void onSetMute();
/**
* 音量调节指令
* @param volumeControl
* @param volumeValue
*/
void onAdjustVolume(String volumeControl, String volumeValue);
}IInstructionListener
IInstructionListener - 特殊指令
public interface IInstructionListener extends IDirectiveListener {
/**
* 电量查询指令
*/
void onInquireEnergy();
/**
* 展示功能指令
*/
void onShowFeatures();
}IErrorListener
IErrorListener - 错误监听
public interface IErrorListener extends IDirectiveListener {
/**
* 错误监听
* @param code 错误码
* @param errorDescription 错误描述
*/
void onError(int code, String errorDescription);
}IStateListener
IStateListener - 指令处理状态监听
public interface IStateListener extends IDirectiveListener {
/**
* 当NLU能力识别完成本次对话请求中的用户事件，
* SDK 开始向开发者回传本次对话请求返回的事件指令（Directives）时回调
*/
void onDirectiveStart();
/**
* 当 SDK 完成了本次对话请求返回的全部事件指令的回传时回调
*/
void onDirectiveStop();
}