接入说明

只需简单 3 步,即可将客服功能加入你的 App:

  1. 添加 SDK 到项目中。
  • Android Studio: 在工程 build.gradle 文件中添加依赖即可。Download

    // 最新版本可参考 Download 徽章后对应的数值
    compile 'com.qiyukf.unicorn:unicorn:+'
    
  • Eclipse: 先下载 SDK,然后解压缩,将得到的 unicorn 文件夹作为库工程模块导入到你的工程中,并添加模块依赖。然后将 assets 文件夹的内容拷贝你的主工程的 assets 目录中,将 AndroidManifest 文件中的内容拷贝到你的主工程的 manifest 文件中,并将 manifest 中的 ${applicationId} 替换为你的包名。

  1. 在你的 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 的实现代码可参考 图片加载 一节。

  2. 在你的 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源码,开发者可以参考源码;更多的时候是需要开发者自己本地调试代码,可以通过断点跟踪等基本且有效的方法来定位和排查问题。

SDK包具体内容

sdk
├── libs
│   ├── qiyu-sdk-x.y.z.jar
│   └── android-support-v4.jar
├── res
│   └── ***
└── assets
    └── ***

上面文件中,qiyu-sdk-x.y.z.jar 是网易七鱼的 SDK 包,res 和 assets 为 SDK 所依赖的资源文件。

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.** {*;}

初始化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();
            }
        }
    }
}

初始化包括两个部分,一是本地数据的初始化,二是从七鱼的服务器获取一些配置信息操作。本地数据的初始化是同步的,主要是检查本地是否已经有可以聊天的账号,如果有了,还会做一些缓存数据的初始化操作。如果没有,才会进入到第二部分,去七鱼服务器获取聊天账号。第二部分是异步操作,会在后台自动完成。