6.2 代码快速集成
在会话界面需要添加SDK lib中的代码，将消息服务集成到您的项目中。具体接口调用和代码添加如下。
6.2.1 初始化SDK
SDK 初始化参考 5.1。
6.2.2 开启消息服务
在会话界面 Activity 的 onCreate 中调用:
// 开启消息服务
V5ClientAgent.getInstance().start(Context context, V5MessageListener listener);
其中 V5MessageListener 是消息回调监听器:
public interface V5MessageListener {
public void onConnect(int unreadSize); // 建立连接，参数：连接后获取到未读消息数量
public void onMessage(String json); // 返回消息为json字符串(兼容后期接口类型扩展)
public void onMessage(V5Message message); // 返回消息对象
public void onError(V5KFException error); // 返回异常信息
public void onServingStatusChange(ClientServingStatus status); // 客户服务状态改变
}
初始化内容包括:
- 设置消息回调监听器;
- 向 V5 认证服务进行客户端认证，根据
AndroidManifest配置的站点信息和客户端生成的客户 ID 向认证服务器认证(这之前可进行客户端用户信息设置，参见 6.2.5)，获取会话参数; - 认证成功并返回参数后开启
V5ClientService消息服务。
6.2.3 消息接口调用
获得开场白:
/**
* 获得开场消息
* @param mode 开场白模式(定义见5.4)
* @param param 可变参数
*/
public void getOpeningMessage(ClientOpenMode mode, String param)
发送消息调用:
V5ClientAgent.getInstance().sendMessage (V5Message message, MessageSendCallback callback);
发送消息的第一个参数是 V5Message 消息对象，支持发送文本消息、位置消息、图片消息、控制消息:
// 新建文本消息
V5TextMessage textMsg = V5MessageManager.getInstance().obtainTextMessage(“消息内容”);
// 新建位置消息
V5LocationMessage locationMsg = V5MessageManager.getInstance().
obtainLocationMessage(
double latitude, // 纬度
double longitude, // 经度
double accuracy, // 精度,可为0
String address); // 地址描述，可为null
// 新建图片消息——发送本地图片
V5ImageMessage imageMsg = V5MessageManager.getInstance().obtainImageMessage(
String filePath); // 本地图片路径
// 新建图片消息——发送网络图片
V5ImageMessage imageMsg = V5MessageManager.getInstance().obtainImageMessage(
String pic_url, // 图片URL
String media_id); // 媒体ID，可为null
// 新建控制消息
V5ControlMessage controlMsg = V5MessageManager.getInstance().obtainControlMessage(
int code, // 代码
int argc, // 参数数量，可为0，即参数可为空
String argv); // 参数值(字符串)，可为null
// 目前开放的控制消息为转人工客服消息:code = 1，其他参数为空，示例如下:
V5Message msg = V5MessageManager.getInstance().obtainControlMessage(1, 0, null);
发送消息的第二个参数 MessageSendCallback 为消息发送结果回调:
public interface MessageSendCallback {
public void onSuccess(V5Message message); // 成功
public void onFailure(V5Message message, int statusCode, String desc); // 失败
}
转人工客服可调用:
// 请求人工客服服务
V5ClientAgent.getInstance().switchToArtificialService(MessageSendCal lback callback);
不需要客服消息服务时需要关闭消息服务:
V5ClientAgent.getInstance().onDestroy(); // 关闭消息服务
关闭消息服务表示用户下线，即无法继续接收消息，当用户再次进入会话界面时才能继续消息请求和接收，用户下线后消息将会缓存。若设置了离线消息的推送服务器地址，您的服务器将会收到用户下线后的离线消息，可选择自行推送到您的 APP，或者保存到您的服务端，此外可选择对接到第三方推送平台，目前已支持腾讯信鸽推送和百度云推送。
6.2.4 生命周期处理
添加到会话界面 Activity 中 onStart、onStop 和 onDestroy 中处理的代码:
@Override
protected void onStart() {
super.onStart();
V5ClientAgent.getInstance().onStart(); // 通知消息服务 onStart
}
@Override
protected void onStop() {
super.onStop();
V5ClientAgent.getInstance().onStop(); // 通知消息服务 onStop
}
@Override
protected void onDestroy() {
super.onDestroy();
V5ClientAgent.getInstance().onDestroy();// 关闭消息服务，通知消息服务onDestroy
}
6.2.5 用户信息设置
V5ClientConfig 的配置需要在执行 SDK 的 startChat*** 方法初始化之前设置，非必须，但设置易识别的用户信息有助于客服识别客户，提高客服效率和服务质量，具体代码如下:
V5ClientConfig config = new V5ClientConfig(Context context);
//当nickname、uid、avatar、device_token等配置项配置完下次需要修改并向座席更新时
//需要在之前调用shouldUpdateUserInfo()，这样才会向服务端更新这几个配置项
// config.shouldUpdateUserInfo();
//【建议】设置昵称
config.setNickname("昵称");
//【建议】设置头像URL
config.setAvatar("http://static.v5kf.com/images/web/fodder/xlogo.png");
/**
*【建议】设置用户OpenId，以识别不同登录用户，不设置则默认由SDK生成，替代v1.2.0之前的uid,
* openId将透传到座席端(长度32字节以内，建议使用含字母数字和下划线的字符串，尽量不用特殊字符，若含特殊字符系统会进行URL encode处理，影响最终长度和座席端获得的结果)
*/
config.setOpenId("android_sdk_test");
//config.setUid(uid); //【弃用】请使用setOpenId替代
// 设置性别 0-未知 1-男 2-女
config.setGender(1);
// 设置用户VIP等级(0-5)
config.setVip(0);
// 设置device_token:集成第三方推送(腾讯信鸽、百度云推)时设置此参数以在离开会话界面时接收推送消息
config.setDeviceToken(String device_token);
推送消息接受会收到后，在通知栏点击时需要打开客服会话界面。若您使用第三方推送平台将会返回一组自定义参数 "v5_action" : "new_message"，以此区分是否是来自 V5 智能客服系统的消息；若您使用自己的推送服务器，您可以在接收到消息后自行标记此消息并推送到客户端 APP(根据 device_token 识别接收客户端)，然后启动您自定义的客服会话界面。
6.2.6 查询会话消息
- 1.当开启消息缓存时，可以通过下面的接口查询缓存的历史消息:
V5ClientAgent.getInstance().getMessages(int offset, int size, OnGetMessagesCallback callback)
其中 offset 为请求起始位置，size 为最多返回消息数，返回的 finish 为 true 时说明已没有更多会话，offset 和 size 均为 0 时表示查询当前会话全部消息。OnGetMessagesCallback 为获取历史消息的回调，以表示历史消息获取成功，参数为消息对象列表:
public interface OnGetMessagesCallback {
// 执行完成
public void complete(List<V5Message> msgs, int offset, int size, boolean finish);
}
此外，提供清空历史消息缓存接口:
V5ClientAgent.getInstance().clearLocalHistoricalMessages(Context context);
- 2.查询离线消息
V5ClientAgent.getInstance().getOfflineMessages(int offset, int size, OnGetMessagesCallback callback)
其中 offset 为请求起始位置，size 为最多返回消息数，返回的 finish 为 true 时说明已没有更多会话，offset 和 size 均为 0 时表示查询当前会话全部消息， OnGetMessagesCallback 为获取离线消息的回调，使用 UI 库开发时不需要设置此回调(设为 null)，SDK 自行处理此回调获得的消息并显示在消息列表。
注:
getOfflineMessages接口的offset参数已被后台忽略，设置无效，一次查询全部离线消息，offset 和 size 均设定为 0 即可。
6.2.7 查询服务状态
获取会话服务状态:
V5ClientAgent.getInstance().getStatus();
状态返回在 V5MessageListener 的 onServingStatusChange 中回调:
public void onServingStatusChange(ClientServingStatus status);
客服状态值和含义如下:
public enum ClientServingStatus {
clientServingStatusRobot, // 机器人服务
clientServingStatusQueue, // 排队中(等待人工客服，当前为机器人服务)
clientServingStatusWorker, // 人工服务
clientServingStatusInTrust; // 人工交给机器人托管
}
6.2.8 其他设置
客户端的调试日志显示和其他配置(以下设置值为 SDK 内默认值):
// V5客服系统客户端配置(以下值均为默认值，仅作示例，不需修改可不必设置)
V5ClientConfig config = V5ClientConfig.getInstance(this);
V5ClientConfig.USE_HTTPS = true; // 使用加密连接，默认true
V5ClientConfig.SOCKET_TIMEOUT = 20000; // 默认设置请求超时时间20s
// 是否需要界面支持(涉及到离线消息自动获取和本地缓存)
V5ClientConfig.UI_SUPPORT = false; // 使用UI快速集成须设此项为true
// 是否允许本地缓存消息(UI_SUPPORT true时需设置此项为true)
config.setLocalMessageCacheEnable(true);
config.setHeartBeatEnable(true); // 允许发送心跳包保活
config.setHeartBeatTime(30000); // 心跳包间隔30000ms
config.setShowLog(true); // 显示日志，默认为true
config.setLogLevel(V5ClientConfig.LOG_LV_DEBUG); // 显示日志级别，默认 为全部显示
// 清除缓存，语音、图片等缓存在应用data/cache目录下
V5ClientAgent.clearCache(Context context);