开发指南

# CRM对接

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

# 上报用户信息

获取[QYSDK sharedSDK]单例后，调用如下接口上传用户信息：

/**
 *  设置用户信息，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;

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

  • 传入的userId为空字符串，回调中 error.code = QYLocalErrorCodeInvalidUserId；
  • 当前已登录某个userId，再次调用接口传入不同userId，回调中 error.code = QYLocalErrorCodeNeedLogout；
  • 请求失败或超时，回调中error为具体的网络错误。

QYUserInfo类用于承载用户信息，提供如下属性：

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

其中data属性采用数组的 JSON 字符串形式描述用户详细信息，数组中每个元素代表一个数据项，数据项以<key, value>对形式为基础，增加了额外字段以控制显示样式，具体可参考 网易七鱼企业信息对接开发指南 。 示例代码：

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 用于排序，显示数据时数据项按index值升序排列；不设定index的数据项将排在后面；index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列
label 该项数据显示的名称。
value 该数据显示的值，类型不做限定，根据实际需要进行设定。
href 超链接地址。若指定该值，则该项数据将显示为超链接样式，点击后跳转到其值所指定的 URL 地址。
hidden 是否隐藏该item。目前仅对mobile和email有效。
isCustomField 是否属于自定义字段。如果是，则尝试匹配自定义字段名称并更新值，目前只支持 文本、数字、时间(13位数字时间戳)、单选、多选(用 ### 分割选中值，其中###前后都有空格)。

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

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

# 错误码

- (void)setUserInfo:(QYUserInfo *)userInfo userInfoResultBlock:(QYResultCompletionBlock)userInfoBlock
- (void)setUserInfo:(QYUserInfo *)userInfo userInfoResultBlock:(QYResultCompletionBlock)userInfoBlock authTokenResultBlock:(QYCompletionBlock)authTokenBlock;

上面两个方法的回调userInfoBlock，如果返回失败，错误码对应原因如下：

code 原因
200 成功
0 未知错误
1 错误参数
2 必须为融合SDK
3 帐号错误-底层通信IM帐号未登录
4 userId错误，应与帐号相同
5 userId变化，应走帐号切换逻辑，先调用logout
8006 不合法请求
1001 appkey不存在
1002 deviceId错误
1003 其他错误
1004 auth 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] setUserInfoForFusion:userInfo userInfoResultBlock:^(BOOL success, NSError *error) {
   //用户信息上报结果回调      
} authTokenResultBlock:^(BOOL success) {
   //token校验结果回调
}];

# 多端登录

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

# 注销用户

App 退出账号时须调用 SDK 的注销操作。由[QYSDK sharedSDK]单例提供接口：

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

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

# 切换用户

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

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

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

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

# 常见问题

  1. 相关接口的正确调用顺序及时机：
    • 若您的 App 客服功能依赖用户登录，则应在 用户主动登录帐号/App启动后自动登录帐号 流程结束后调用QYSDK的setUserInfo:接口将userId及对应的信息data数据上传，即帐号登录成功后设置用户信息；帐号 退出/注销登录 后调用QYSDK的logout:接口。
    • 若您的 App 客服功能不依赖用户登录，即匿名状态下也可咨询客服，则匿名状态下无需调用setUserInfo:接口，SDK 会在启动时默认创建一个用于底层通信的匿名帐号，setUserInfo:的作用只是与此帐号进行绑定；如若有匿名下上传信息的强需求，需注意只要传入某个 userId ，则后续登录成功后再次上传，属于帐号切换流程，中间需要调用logout:接口登出。
    • setUserInfo:接口应与logout:接口配对使用。
  2. 因setUserInfo:调用时机导致的客服连接状态不稳定
    • 如若需要在咨询客服前上传用户信息，以保证信息的及时更新，请注意客服连接状态是否稳定，如若不稳定，有可能是开启了服务端的帐号优化逻辑，存在切换长连接的情况，请及时调整接口调用时机。

← 消息推送 →