# 接入说明

只需简单 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);
    }
};

← 概述 CRM对接 →