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:接口上报新的用户信息。
/**
* 获取当前设置的用户信息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帐号未登录 |
| 4 | userId错误,userId不应该为空 |
| 5 | userId变化,应走帐号切换逻辑,先调用logout |
| 8006 | 不合法请求 |
| 1001 | appkey不存在 |
| 1002 | deviceId错误 |
| 1003 | 其他错误,具体原因需要咨询服务端 |
| 1004 | auth token错误 |
上面setUserInfo方法(上报用户信息)的回调userInfoBlock,如果返回失败,错误码对应原因如下:
其中setUserInfo: userInfoResultBlock: 方法回调上报结果,存在以下错误可能:
- 传入的userId为空字符串,回调中 error.code = QYLocalErrorCodeInvalidUserId;
- 当前已登录某个userId,再次调用接口传入不同userId,回调中 error.code = QYLocalErrorCodeNeedLogout;
- 请求失败或超时,回调中error为具体的网络错误。
QYUserInfo类用于承载用户信息,提供如下属性:
其中 data 属性采用数组的 JSON 字符串形式描述用户详细信息,数组中每个元素代表一个数据项,数据项以 <key, value> 对形式为基础,增加了额外字段以控制显示样式。
data字段
data访客信息为一个 Json 数组,该数组中的 item 目前可包含以下字段
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | String | 是 | 数据项的名称,用于区别不同的数据。其中real_name、mobile_phone、email为保留字段,分别对应客服工作台用户信息中的“姓名”、“手机”、“邮箱”这三项数据。保留关键字对应的数据项中,index、label属性将无效,其显示顺序及名称由网易七鱼系统指定 |
| value | Object | 是 | 该数据显示的值,类型不做限定,根据实际需要进行设定 |
| label | String | 是 | 该项数据显示的名称 |
| index | int | 否 | 用于排序,显示数据时数据项按index值升序排列;不设定index的数据项将排在后面;index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列 |
| href | String | 否 | 超链接地址。若指定该值,则该项数据将显示为超链接样式,点击后跳转到其值所指定的 URL 地址 |
| hidden | boolean | 否 | 仅对mobile_phone、email两个保留字段有效,表示是否隐藏对应的数据项,true为隐藏,false为不隐藏。若不指定,默认为false不隐藏 |
| isCustomField | boolean | 否 | 是否属于自定义字段。如果是,则尝试匹配自定义字段名称并更新值,目前只支持 文本、数字、时间(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];| 属性 | 说明 |
|---|---|
| real_name | 用户姓名。 |
| mobile_phone | 用户手机号,可以隐藏。 |
| 用户的邮箱账号,可以隐藏。 | |
| avatar | 用户的头像,可以在客服端显示。访客端的用户头像不会使用该字段。 |
crm信息格式错误提示
传入的数据不是数组格式:
🟥🟥🟥🟥🟥🟥🟥🟥🟥 [ERROR] crm信息格式错误,应为数组
数组中存放的不是字典格式:
🟥🟥🟥🟥🟥🟥🟥🟥🟥 [ERROR] crm信息格式错误,json数组中应为字典
缺少key字段或者value字段:
🟥🟥🟥🟥🟥🟥🟥🟥🟥 [ERROR] crm信息格式错误,数据中必须包含key和value
自定义信息缺少label字段:
🟥🟥🟥🟥🟥🟥🟥🟥🟥 [ERROR] crm信息格式错误,数据中必须包含label
常见问题
本节汇总开发者接入和使用过程中常见问题,并给出对应处理建议。
CRM对接常见问题
- 相关接口的正确调用顺序及时机:
- 若您的 App 客服功能依赖用户登录,则应在 用户主动登录帐号/App启动后自动登录帐号 流程结束后调用QYSDK的setUserInfo:接口将userId及对应的信息data数据上传,即帐号登录成功后设置用户信息;帐号 退出/注销登录 后调用QYSDK的logout:接口。
- 若您的 App 客服功能不依赖用户登录,即匿名状态下也可咨询客服,则匿名状态下无需调用setUserInfo:接口,SDK 会在启动时默认创建一个用于底层通信的匿名帐号,setUserInfo:的作用只是与此帐号进行绑定;如若有匿名下上传信息的强需求,需注意只要传入某个 userId ,则后续登录成功后再次上传,属于帐号切换流程,中间需要调用logout:接口登出。
- setUserInfo:接口应与logout:接口配对使用。
- 因setUserInfo:调用时机导致的客服连接状态不稳定
- 如若需要在咨询客服前上传用户信息,以保证信息的及时更新,请注意客服连接状态是否稳定,如若不稳定,有可能是开启了服务端的帐号优化逻辑,存在切换长连接的情况,请及时调整接口调用时机。
- ios sdk 中调用 setUserInfo 的常见错误码说明:
这篇文档有帮助吗?