# 接入说明
只需简单 3 步,即可将客服功能加入你的 App:
添加 SDK 到项目中。使用Android Studio,在工程 build.gradle 文件中添加依赖即可。最新版本地址 (opens new window)
// 最新版本可查看上面的链接地址 implementation 'com.qiyukf.unicorn:unicorn:+'
当 App 接入工程没有升级到 Android X 请使用 <= 5.7.7 的版本,七鱼 SDK 在 > V5.7.7 升级了 Android Support 库到 Android X ,如果接入工程中使用的是 Android Support 库,那么接入 > V5.7.7 版本会出现 Merge dex 冲突问题。
- 在你的 Application 类的
onCreate
函数中,加入以下初始化代码:
注意:方法二没有隐私问题,请按照方法二接入。
public class YourApplication extends Application { public void onCreate() { // ... your codes // appKey 可以在七鱼管理系统->设置->App 接入 页面找到 Unicorn.init(this, "appKey", options(), new UnicornImageLoader()); // ... your codes } // 如果返回值为null,则全部使用默认参数。 private YSFOptions options() { YSFOptions options = new YSFOptions(); options.statusBarNotificationConfig = new StatusBarNotificationConfig(); return options; }
上面代码中,UnicornImageLoader 可根据你 App 中图片加载模块做自定义实现,以免 SDK 中引入第三方图片管理库后造成与 App 的冲突或者浪费。在 demo 中,实现了依赖于 UniversalImageLoader 的 UILImageLoader。其代码以及依赖于 fresco、Glide、Picasso 的实现代码可参考 图片加载 一节。
在你的 App 的合适页面添加客服入口按钮,并在响应函数中加入如下代码:
String title = "聊天窗口的标题"; /** * 设置访客来源,标识访客是从哪个页面发起咨询的,用于客服了解用户是从什么页面进入。 * 三个参数分别为:来源页面的url,来源页面标题,来源页面额外信息(保留字段,暂时无用)。 * 设置来源后,在客服会话界面的"用户资料"栏的页面项,可以看到这里设置的值。 */ ConsultSource source = new ConsultSource(sourceUrl, sourceTitle, "custom information string"); /** * 请注意: 调用该接口前,应先检查Unicorn.isServiceAvailable(), * 如果返回为false,该接口不会有任何动作 * * @param context 上下文 * @param title 聊天窗口的标题 * @param source 咨询的发起来源,包括发起咨询的url,title,描述信息等 */ Unicorn.openServiceActivity(context, title, source);
在打开的页面中,用户就可以咨询客服了。
由于开发环境的不同,很多情况下会出现集成报错或者配置无效的问题。我们官网提供了demo源码,开发者可以参考源码;更多的时候是需要开发者自己本地调试代码,可以通过断点跟踪等基本且有效的方法来定位和排查问题。官网demo安装包,demo源码及SDK开发手册查看地址 (opens new window)。
# SDK包具体内容
在 > V5.7.7 的 SDK 中我们升级了 Android Support 库到 Android X。所以如果 App 工程中没有升级到 Android X 可以使用 <= 5.7.7 的版本
// <= V5.7.7 版本结构
sdk
├── libs
│ ├── qiyu-sdk-x.y.z.jar
│ └── android-support-v4.jar
├── res
│ └── ***
└── assets
└── ***
// > 5.7.7 版本结构
sdk
├── libs
│ ├── qiyu-sdk-x.y.z.jar
├── res
│ └── ***
└── assets
└── ***
上面文件中,qiyu-sdk-x.y.z.jar 是网易七鱼的 SDK 包,res 和 assets 为 SDK 所依赖的资源文件。
在 SDK <= 5.7.7 版本 android-support-v4.jar 为工程依赖的外部库,所需最低版本为23.0.0(Android 6.0权限管理适配)。如果你的 App 也依赖了这个 jar 包,可以将你的工程中的依赖移除,或者将这个库移动到一个更基础的库工程中做依赖。如果是使用 Android Studio 接入,SDK 工程的 build.gradle 文件已经添加了依赖,无需理会这个文件。
# 混淆配置
如果你的 apk 最终会经过代码混淆,请在 proguard 配置文件中加入以下代码:
-dontwarn com.qiyukf.**
-keep class com.qiyukf.** {*;}
-dontwarn com.netease.**
-keep class com.netease.** {*;}
-dontwarn org.slf4j.**
-keep class org.slf4j.** { *; }
# 初始化SDK
网易七鱼 SDK 需要接收消息推送,因此有一个后台进程,进程名为 "packageName:core"。我们知道,Application 的 onCreate 在各个进程中都会被调用,包括 UI 主进程和七鱼的推送进程。在实现 Application 的 onCreate 时,如果需要在 onCreate 中调用除 init 接口外的其他接口,应先判断当前所属进程,并只有在当前是 UI 进程时才调用。SDK 的 init 接口无需做额外判断,SDK 会自动识别是否需要初始化。另外,要注意不要在主进程外的其他进程中再调用 Unicorn 提供的接口(init
除外)。判断当前进程是否是在主进程的代码示例如下:
public static boolean inMainProcess(Context context) {
String mainProcessName = context.getApplicationInfo().processName;
String processName = getProcessName();
return TextUtils.equals(mainProcessName, processName);
}
/**
* 获取当前进程名
*/
private static String getProcessName() {
BufferedReader reader = null;
try {
File file = new File("/proc/" + android.os.Process.myPid() + "/" + "cmdline");
reader = new BufferedReader(new FileReader(file));
return reader.readLine().trim();
} catch (IOException e) {
return null;
} finally {
if (reader != null) {
try {
reader.close();
} catch (IOException e) {
e.printStackTrace();
}
}
}
}
初始化包括两个部分,一是本地数据的初始化,二是从七鱼的服务器获取一些配置信息操作。本地数据的初始化是同步的,主要是检查本地是否已经有可以聊天的账号,如果有了,还会做一些缓存数据的初始化操作。如果没有,才会进入到第二部分,去七鱼服务器获取聊天账号。第二部分是异步操作,会在后台自动完成。
# 初始化方法二
在 V5.15.0 版本中 SDK 开放了 Unicorn.config
和 Unicorn.initSdk
方法,通过这两个方法可以达到和 Unicorn.init
一样的效果。
具体使用方法为在 Application 的 onCreate 中调用 Unicorn.config
方法,然后在使用客服之前调用 Unicorn.initSdk
方法(因为该方法需要调用 Http 接口,所以尽可能提前调用,且不要重复调用)。
建议在APP主界面调用Unicorn.initSdk
方法,这样当下次打开APP的时候,若客服主动发送消息,则可以立刻收到。不要调用 Unicorn.initSdk
后立即进入客服界面,中间间隔至少2.5S,等七鱼SDK初始化完成。
具体使用方法如下:
public class YourApplication extends Application {
public void onCreate() {
//初始化方法不要限制进程,也就是说不要只在主进程中初始化
Unicorn.config(this, "appKey", options(), new UnicornImageLoader());
}
}
public class MainActivity extends Activity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
Unicorn.initSdk();
}
}
# 海外版本
在SDK 7.8.0 版本,新增了海外版本SDK,海外版本与国内版本接入方式一样,在工程 build.gradle 文件中添加依赖即可。最新海外版本地址 (opens new window)
// 最新海外版本可查看上面的链接地址
implementation 'com.qiyukf.unicorn:unicorn_abroad:+'
- 注意:使用海外版SDK只能连接访问海外域名企业,与国内版不互通。海外版下载中心地址 (opens new window)
# 视频客服
在 SDK V7.9.1 版本,新增了视频客服功能:
在七鱼SDK的基础上,添加视频客服 SDK 到项目中。 在工程 build.gradle 文件中添加依赖。最新视频客服版本地址 (opens new window)
// 最新视频客服版本可查看上面的链接地址 implementation 'com.qiyukf.unicorn:video:+'
进行视频客服会话。 在
ConsultSource
中增加了isEnableVideo参数,用于是否进行视频客服会话,默认为false。如果此参数设置为true,表示进行视频客服会话。进行屏幕共享时,需要配置屏幕共享点击悬浮窗时回到的界面,推荐配置到聊天界面,否则SDK拿不到需要回到的界面。
options.onVideoFloatBackIntent = new OnVideoFloatBackIntent() { @Override public void onVideoFloatBackIntent(Context context) { // 启动聊天界面 ConsultSource source = new ConsultSource("来自视频客服", "视频客服", null); Unicorn.openServiceActivity(context, "视频客服来的", source); } };