CRM对接

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

上报用户信息

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

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

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

获取[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为具体的网络错误。

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告知结果。

注销用户

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