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

CRM 对接

上报用户信息

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

上报用户信息

方法描述

七鱼 SDK 允许 App 的用户以匿名方式向客户咨询；如果 App 希望客服识别当前用户，可以通过 Unicorn.setUserInfo() 上报访客信息。

注意：

  1. 在调用该方法前，一定要调用Unicorn.initSdk()方法。
  2. setUserInfo是一个异步方法，如需在打开客服界面前上报用户信息，请参考在回调中打开客服界面。
  3. 用户信息为可选项，七鱼对相关字段内容不做强制要求，使用方需依法依规处理客户数据。​
  4. 关联用户账户。调用过该接口后，客服即可知道当前用户是谁，并可以调看该用户之前发生过的访问记录。通过该接口，SDK还会把 App 端相同用户 ID 的咨询记录整合在一起。如果调用 setUserInfo 接口前是匿名状态，那么匿名状态下的聊天记录也会被整合到新设置的这个用户下面。
  5. 提供用户的详细资料。通过设置 YSFUserInfo 的 data 字段，App 能把用户的详细信息告诉给客服，这些信息会显示在客服会话窗口的用户信息栏中。该字段具有很强的可扩展性，具体请见本节后面的描述。

方法说明

public static boolean setUserInfo(YSFUserInfo userInfo)

YSFUserInfo

名称类型必填说明
userIdString是用户在企业产品中的标识，便于后续客服系统中查看该用户在产品中的相关信息 。若要指定用户信息，不显示默认的（guestxxx用户姓名），就必须传userId
authTokenString否用户认证，参考服务端校验 token
dataString否用户在企业中的其他详细信息，JSON数据格式

data字段

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

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

代码示例

设置访客信息的示例如下：

YSFUserInfo userInfo = new YSFUserInfo();
// App 的用户 ID
userInfo.userId = "uid";
// 当且仅当开发者在管理后台开启了 authToken 校验功能时，该字段才有效
userInfo.authToken = "auth-token-from-user-server";
// CRM 扩展字段
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"}
]";
Unicorn.setUserInfo(userInfo);

上报用户信息回调

建议在进入客服界面前调用上报用户信息的方法，并在callback的成功接口中打开客服界面

调用setUserInfo的重载方法

方法说明

public static boolean setUserInfo(YSFUserInfo userInfo，RequestCallback<Void> callback)

RequestCallback

异步接口可通过 RequestCallback 和 RequestCallbackWrapper 两种方式设置回调函数。

异步接口回调函数说明
RequestCallback需要实现三个接口：
成功onSuccess, 失败 onFailed, 异常 onException
RequestCallbackWrapper需要实现 onResult。封装了成功、失败和异常三个接口，在参数上进行区分

代码示例

YSFUserInfo userInfo = new YSFUserInfo();
// App 的用户 ID
userInfo.userId = "uid";
// 当且仅当开发者在管理后台开启了 authToken 校验功能时，该字段才有效
userInfo.authToken = "auth-token-from-user-server";
// CRM 扩展字段
userInfo.data="[
    {"key":"real_name", "value":"土豪"},
    {"key":"mobile_phone", "hidden":true, "value":"13800000000"},
    {"key":"email", "value":"13800000000@163.com"},
    {"key":"avatar", "value": "https://qiyukf.com/def_avatar.png"},
    {"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"}
]";

Unicorn.setUserInfo(userInfo, new RequestCallback<Void>() {
            @Override
            public void onSuccess(Void aVoid) {
                // 成功回调里面打开客服界面，crm信息已经上报成功
                Unicorn.openServiceActivity(this, "七鱼客服", null);
            }
            @Override
            public void onFailed(int errorCode) {
                // 可以根据下表的错误码，查看错误发生原因，客户可以根据自己的情况自行处理。如：
                // if(errorCode == 701) {
                //   Toast.makeText(this, "UserInfo id 为 null", Toast.LENGTH_SHORT).show();
                // }
                // 失败回调里也可以打开客服界面，只不过会随机生一个匿名的用户，以Geust开头
            	Unicorn.openServiceActivity(this, "七鱼客服", null);
            }
            @Override
            public void onException(Throwable throwable) {
                // 异常回调里也可以打开客服界面，只不过会随机生一个匿名的匿名的用户，以Geust开头
            	Unicorn.openServiceActivity(this, "七鱼客服", null);
            }
        });

注销用户

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

注销用户

为了区分不同的 App 用户，当 App 端用户注销后，需要调用 Unicorn.logout() 告诉 SDK。SDK 此时会关闭前一个用户的聊天记录，并重新分配一个新的聊天账号，以和之前的用户区分。注销之后，客服再给前面用户发送消息将进入留言，等到该用户下次在同一台设备上登录后才能看到。如果 App 用户注销后不调用该接口，七鱼无法感知用户已经变更，当前设备仍可能收到前一个用户的消息，造成混乱。

注意，该接口不允许直接从一个账号切换到另外一个账号，否则会报错702。

方法说明

public static void logout()

注销用户信息回调

如需注销成功的回调，则可以使用logout的重载方法

方法说明

public static void logout(RequestCallback<Void> callback)

RequestCallback

异步接口可通过 RequestCallback 和 RequestCallbackWrapper 两种方式设置回调函数。

异步接口回调函数说明
RequestCallback需要实现三个接口：
成功onSuccess, 失败 onFailed, 异常 onException
RequestCallbackWrapper需要实现 onResult。封装了成功、失败和异常三个接口，在参数上进行区分

代码示例

Unicorn.logout(new RequestCallback<Void>() {
	@Override
	public void onSuccess(Void param) {
   		// 登出成功             
	}
	@Override
	public void onFailed(int code) {
    }

	@Override
	public void onException(Throwable exception) {

	}
});

切换与更新用户

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

切换用户

若当前已调用 Unicorn.setUserInfo() 上报了用户信息，假设传入的用户 ID 为 userIdA；如需切换至账号 userIdB，应先注销当前账号，再上报新用户信息。

Unicorn.logout() 是异步操作。切换账号时应使用带回调的重载方法，并在注销成功回调中调用 Unicorn.setUserInfo()；请勿连续调用两个方法或依赖固定延时，否则旧账号可能尚未清理完成，并返回错误码 702。

从 Android SDK 11.10.0 开始，可通过 Unicorn 获取当前已上报的用户 ID：

/**
 * 获取当前通过 setUserInfo() 上报的用户 ID。
 *
 * @return 当前用户 ID；SDK 未初始化或未上报用户时返回 null
 */
@Nullable
public static String getUserId()

注销成功回调触发前，getUserId() 仍可能返回原用户 ID，应以注销回调结果作为账号切换的依据。

代码示例

final YSFUserInfo newUserInfo = new YSFUserInfo();
newUserInfo.userId = "userIdB";
newUserInfo.data = "[]";

if (!Unicorn.isInit()) {
    return;
}

String currentUserId = Unicorn.getUserId();
if (TextUtils.isEmpty(currentUserId)
        || TextUtils.equals(currentUserId, newUserInfo.userId)) {
    // 匿名用户直接上报；userId 不变时更新用户信息
    Unicorn.setUserInfo(newUserInfo);
} else {
    Unicorn.logout(new RequestCallback<Void>() {
        @Override
        public void onSuccess(Void param) {
            // 注销完成后再上报新用户，避免返回错误码 702
            Unicorn.setUserInfo(newUserInfo);
        }

        @Override
        public void onFailed(int code) {
            // 注销失败，保留当前账号并根据错误码处理
        }

        @Override
        public void onException(Throwable exception) {
            // 注销异常，保留当前账号并处理异常
        }
    });
}

更新用户信息

如已经上报过用户信息，想要更新用户信息，则需要保证YSFUserInfo.userId不变，只需修改YSFUserInfo.data数据，则可以更新成功。

错误码与日志

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

常见错误码及日志

上述方法返回错误码说明：

错误码错误描述
310登录IP或MAC被禁
315内部帐户不允许在该地址登陆
403用户被封禁
408操作超时，一般是网络出现了问题，如网络波动
414参数错误
415网络连接出现问题
701设置 UserInfo id 为 null
702没有退出上一个 user 就直接调用了 setUserInfo
703使用融合 SDK 没有先登录云信
1000网络错误或者网络波动
1001appkey不存在
1002deviceId错误
1003其他错误
1004authToken校验错误

当上报用户信息成功后，在会话界面看不到客户信息，并且在AndroidStudio的Logcat出现以下错误日志，则表示data字段不符合要求：

错误日志错误描述
CRM data is not a valid JSON arraydata数据不是json数组或不符合json格式要求
CRM data structure invalid: missing key or valuedata数据中每个对象必须包含key和value字段，如果不是保留关键字，则必须包含label字段

常见问题

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

常见问题

Q: 调用setUserInfo()设置的用户信息无法生效

A: 请先检查自己的接入代码，是否在设置用户信息后立即打开了聊天窗口，这种情况下用户信息很可能设置失败。设置用户信息是一个异步的过程；如果需要保证用户信息设置成功，则应该在成功回调中打开聊天窗口或进行后续操作。

Q: 如果注销用户调用报错408或其他错误

A: 首先请升级SDK到9.11.1及以上版本，如果还有问题，则408报错就是网络问题导致的超时。

这篇文档有帮助吗？

接入说明

上一页

会话配置

下一页

目录

上报用户信息
上报用户信息
上报用户信息回调
注销用户
注销用户
注销用户信息回调
切换与更新用户
切换用户
更新用户信息
错误码与日志
常见错误码及日志
常见问题
常见问题