七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入

CRM 对接

上报用户信息

本节说明如何将访客身份和 CRM 扩展信息上报给七鱼客服系统。

iOS CRM信息对接上报

网易七鱼系统可在访客匿名状态下使用,同时提供对接企业 CRM 系统能力。轻量对接是指企业产品客户端(或网站)在获取到用户账号信息之后,将访客信息作为参数传递给网易七鱼系统,数据将展现在客服工作界面的当前会话和历史会话的 用户资料 标签下。

上报用户信息

获取 QYSDK 单例后,可通过 QYSDK.setUserInfo:userInfoResultBlock: 上传 QYUserInfo 用户信息:

/**
 *  设置用户信息,App帐号登录成功后上传
 *
 *  @param userInfo 用户信息
 *  @discussion 此方法尽量在App帐号登录成功后调用,不应仅在进入客服界面时调用;否则可能会造成客服连接状态不稳定
 *  @discussion 若设置的userId与上次设置不同,即需要实现帐号切换,应先调用logout还原为匿名帐号再进行设置
 */
- (void)setUserInfo:(QYUserInfo *)userInfo;

/**
 *  设置用户信息,App帐号登录成功后上传,带结果回调
 *
 *  @param userInfo 用户信息
 *  @param userInfoBlock userInfo上报结果回调
 *  @discussion 此方法尽量在App帐号登录成功后调用,不应仅在进入客服界面时调用;否则可能会造成客服连接状态不稳定
 *  @discussion 若设置的userId与上次设置不同,即需要实现帐号切换,应先调用logout还原为匿名帐号再进行设置
 */
- (void)setUserInfo:(QYUserInfo *)userInfo userInfoResultBlock:(QYResultCompletionBlock)userInfoBlock;

AuthToken 校验

本节说明用户认证 Token 的配置和校验回调,用于需要服务端身份校验的接入场景。

AuthToken校验

若企业需校验用户的 AuthToken,应先通过如下接口设置:

/**
 *  设置authToken
 */
- (void)setAuthToken:(NSString *)authToken;

然后使用带 AuthToken 校验结果回调的接口去上报用户信息:

/**
 *  设置用户信息,App帐号登录成功后上传,带authToken校验
 *
 *  @param userInfo 用户信息
 *  @param block authToken校验结果回调
 */
- (void)setUserInfo:(QYUserInfo *)userInfo authTokenVerificationResultBlock:(QYCompletionWithResultBlock)block;

/**
 *  设置用户信息,App帐号登录成功后上传,带authToken校验,带结果回调
 *
 *  @param userInfo 用户信息
 *  @param userInfoBlock userInfo上报结果回调
 *  @param authTokenBlock authToken校验结果回调
 *  @discussion 此方法尽量在App帐号登录成功后调用,不应仅在进入客服界面时调用;否则可能会造成客服连接状态不稳定
 *  @discussion 若设置的userId与上次设置不同,即需要实现帐号切换,应先调用logout还原为匿名帐号再进行设置
 */
- (void)setUserInfo:(QYUserInfo *)userInfo userInfoResultBlock:(QYResultCompletionBlock)userInfoBlock authTokenResultBlock:(QYCompletionBlock)authTokenBlock;

收到服务端的校验结果后,会调用接口block告知结果。

示例代码如下:

[[QYSDK sharedSDK] setUserInfo:userInfo userInfoResultBlock:^(BOOL success, NSError *error) {
   //用户信息上报结果回调      
} authTokenResultBlock:^(BOOL success) {
   //token校验结果回调
}];

多端登录

本节说明同一用户在多个终端登录时的支持情况和注意事项。

多端登录

默认情况下,七鱼是不支持多端登录的,同个账号在不同端登录后,账号直接会互踢。如果需要支持多端登录,请联系技术支持解决。 特别需要注意的是,如果开启了多端登录,七鱼服务端发送的系统通知可能会出现混乱,其中一端有可能收不到通知。例如:多端登录的情况下,authTokenBlock可能不会有回调。

注销用户

本节说明用户退出登录或账号失效时如何清理 SDK 账号状态,避免不同用户会话混淆。

注销用户

App 退出账号时须调用 SDK 的 QYSDK.logout: 注销操作:

[[QYSDK sharedSDK] logout:^(BOOL success) {}];

该接口仅在用户退出账号或是账号过期等情况下调用,应避免频繁调用造成反复创建账号。

清理账号信息

V5.1.0 版本后,提供清理账号信息功能,可清理全部或者除当前账号以外的冗余账号信息,通过调用QYSDK.h如下接口清理:

/**
 *  清理账号信息
 *  @discussion 清理全部账号信息会登出当前账号,并新建匿名账号,请在调用完成后使用setUserInfo:接口恢复为有名账号;请在合理时机调用本接口
 *  @param cleanAll 是否清理当前所有账号信息,NO表示清理历史无用账号,YES表示清理全部,必填,默认NO
 *  @param completion 清理缓存完成回调 非必填,可以为nil
 */
- (void)cleanAccountInfoForAll:(BOOL)cleanAll completion:(QYCleanCacheCompletion)completion;

切换与更新用户

本节说明用户信息更新和账号切换流程,帮助开发者正确处理登录态变化。

切换用户

若当前已调用setUserInfo:接口上报了某个用户的信息,假设传入的 ID 为 userIdA ;如若需要切换至帐号 userIdB ,则此流程属于切换用户帐号,应先调用logout:接口注销当前登录的帐号 userIdA ,再调用setUserInfo:接口上报新的用户信息。

可通过QYSDK中的接口获取当前登录的userId:

/**
 *  获取当前设置的用户信息ID
 *
 *  @return 返回当前已设置的用户信息ID
 */
- (NSString *)currentUserID;

同时,V5.13.0 版本开始setUserInfo:接口也会强校验此流程,若未调用注销接口会抛出 error ,其 code 为 QYLocalErrorCodeNeedLogout。

错误码与日志

本节说明 CRM 对接相关错误码、日志提示和排查方向。

setUserInfo 报错原因及错误码说明

setUserInfo报错时,通常是如下格式:QYLocalErrorDomain加上错误码code,具体错误码如下表所示

错误码(code)原因
200成功
-1网络错误
0未知错误
1错误参数
2必须为融合SDK
3帐号错误-底层通信IM帐号未登录
4userId错误,userId不应该为空
5userId变化,应走帐号切换逻辑,先调用logout
8006不合法请求
1001appkey不存在
1002deviceId错误
1003其他错误,具体原因需要咨询服务端
1004auth token错误

上面setUserInfo方法(上报用户信息)的回调userInfoBlock,如果返回失败,错误码对应原因如下:

其中setUserInfo: userInfoResultBlock: 方法回调上报结果,存在以下错误可能:

​

QYUserInfo类用于承载用户信息,提供如下属性:

属性类型必须说明
userIdNSString是用户唯一性标识
dataNSString是数组 JSON 字符串形式,展示在客服端信息

其中 data 属性采用数组的 JSON 字符串形式描述用户详细信息,数组中每个元素代表一个数据项,数据项以 <key, value> 对形式为基础,增加了额外字段以控制显示样式。

data字段

data访客信息为一个 Json 数组,该数组中的 item 目前可包含以下字段

名称类型必填说明
keyString是数据项的名称,用于区别不同的数据。其中real_name、mobile_phone、email为保留字段,分别对应客服工作台用户信息中的“姓名”、“手机”、“邮箱”这三项数据。保留关键字对应的数据项中,index、label属性将无效,其显示顺序及名称由网易七鱼系统指定
valueObject是该数据显示的值,类型不做限定,根据实际需要进行设定
labelString是该项数据显示的名称
indexint否用于排序,显示数据时数据项按index值升序排列;不设定index的数据项将排在后面;index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列
hrefString否超链接地址。若指定该值,则该项数据将显示为超链接样式,点击后跳转到其值所指定的 URL 地址
hiddenboolean否仅对mobile_phone、email两个保留字段有效,表示是否隐藏对应的数据项,true为隐藏,false为不隐藏。若不指定,默认为false不隐藏
isCustomFieldboolean否是否属于自定义字段。如果是,则尝试匹配自定义字段名称并更新值,目前只支持 文本、数字、时间(13位数字时间戳)、单选、多选(用 ### 分割选中值,其中###前后都有空格)

示例代码:

QYUserInfo *userInfo = [[QYUserInfo alloc] init];
userInfo.userId = @"uid";
userInfo.data = @"[{\"key\":\"real_name\", \"value\":\"土豪\"},"
                  "{\"key\":\"mobile_phone\", \"hidden\":true, \"value\":\"13800000000\"},"
                  "{\"key\":\"email\", \"value\":\"13800000000@163.com\"},"
                  "{\"index\":0, \"key\":\"account\", \"label\":\"账号\", \"value\":\"zhangsan\", \"href\":\"http://example.domain/user/zhangsan\"},"
                  "{\"index\":1, \"key\":\"sex\", \"label\":\"性别\", \"value\":\"先生\"},"
                  "{\"index\":5, \"key\":\"reg_date\", \"label\":\"注册日期\", \"value\":\"2015-11-16\"},"
                  "{\"index\":6, \"key\":\"last_login\", \"label\":\"上次登录时间\", \"value\":\"2015-12-22 15:38:54\"},"
                  "{\"index\":7, \"key\":\"tags\", \"label\": \"标签\", \"value\": \"企业,vip\"}"]";
[[QYSDK sharedSDK] setUserInfo:userInfo];

以下key是七鱼使用,他们的排序和标签名是固定的,不能指定index和label。

属性说明
real_name用户姓名。
mobile_phone用户手机号,可以隐藏。
email用户的邮箱账号,可以隐藏。
avatar用户的头像,可以在客服端显示。访客端的用户头像不会使用该字段。

crm信息格式错误提示

传入的数据不是数组格式:

🟥🟥🟥🟥🟥🟥🟥🟥🟥 [ERROR] crm信息格式错误,应为数组

数组中存放的不是字典格式:

🟥🟥🟥🟥🟥🟥🟥🟥🟥 [ERROR] crm信息格式错误,json数组中应为字典

缺少key字段或者value字段:

🟥🟥🟥🟥🟥🟥🟥🟥🟥 [ERROR] crm信息格式错误,数据中必须包含key和value

自定义信息缺少label字段:

🟥🟥🟥🟥🟥🟥🟥🟥🟥 [ERROR] crm信息格式错误,数据中必须包含label

常见问题

本节汇总开发者接入和使用过程中常见问题,并给出对应处理建议。

CRM对接常见问题

  1. 相关接口的正确调用顺序及时机:
  • 若您的 App 客服功能依赖用户登录,则应在 用户主动登录帐号/App启动后自动登录帐号 流程结束后调用QYSDK的setUserInfo:接口将userId及对应的信息data数据上传,即帐号登录成功后设置用户信息;帐号 退出/注销登录 后调用QYSDK的logout:接口。
  • 若您的 App 客服功能不依赖用户登录,即匿名状态下也可咨询客服,则匿名状态下无需调用setUserInfo:接口,SDK 会在启动时默认创建一个用于底层通信的匿名帐号,setUserInfo:的作用只是与此帐号进行绑定;如若有匿名下上传信息的强需求,需注意只要传入某个 userId ,则后续登录成功后再次上传,属于帐号切换流程,中间需要调用logout:接口登出。
  • setUserInfo:接口应与logout:接口配对使用。
  1. 因setUserInfo:调用时机导致的客服连接状态不稳定
  • 如若需要在咨询客服前上传用户信息,以保证信息的及时更新,请注意客服连接状态是否稳定,如若不稳定,有可能是开启了服务端的帐号优化逻辑,存在切换长连接的情况,请及时调整接口调用时机。
  1. ios sdk 中调用 setUserInfo 的常见错误码说明:
错误码原因
200成功
-1网络错误
0未知错误
1错误参数
2必须为融合SDK
3帐号错误-底层通信IM帐号未登录
4userId错误,userId不应该为空
5userId变化,应走帐号切换逻辑,先调用logout
8006不合法请求
1001appkey不存在
1002deviceId错误
1003其他错误,具体原因需要咨询服务端
1004auth token错误

这篇文档有帮助吗?

目录