# 接入说明

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

  1. 添加 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 冲突问题。

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

  1. 在你的 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.configUnicorn.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 V7.9.1 版本,新增了视频客服功能:

  1. 在七鱼SDK的基础上,添加视频客服 SDK 到项目中。 在工程 build.gradle 文件中添加依赖。最新视频客服版本地址 (opens new window)

    // 最新视频客服版本可查看上面的链接地址
    implementation 'com.qiyukf.unicorn:video:+'
    
  2. 进行视频客服会话。 在 ConsultSource中增加了isEnableVideo参数,用于是否进行视频客服会话,默认为false。如果此参数设置为true,表示进行视频客服会话。

  3. 进行屏幕共享时,需要配置屏幕共享点击悬浮窗时回到的界面,推荐配置到聊天界面,否则SDK拿不到需要回到的界面。

    options.onVideoFloatBackIntent = new OnVideoFloatBackIntent() {
        @Override
        public void onVideoFloatBackIntent(Context context) {
            // 启动聊天界面
            ConsultSource source = new ConsultSource("来自视频客服", "视频客服", null);
            Unicorn.openServiceActivity(context, "视频客服来的", source);
        }
    };