react-native-kf5sdk v1.0.6

云客服 React-Native 模块集成指南

一、简介

kf5提供给开发者发送工单、查看工单列表、查看知识库等功能。本模块封装了kf5的相关接口，使用此模块需先注册kf5来获取appid和hostName。注册kf5：登录kf5官网( www.kf5.com )注册kf5账号,进入控制面板 - 系统设置 - 支持渠道 - 移动APP SDK中添加一个APP以获取appid，hostName为你注册的域名，例如：kf5.kf5.com。本模块支持iOS8.0以上和Android 4.1以上。

二、安装与配置

安装

npm install react-native-kf5sdk

即把react-native-kf5sdk导入到工程中的node_modules文件夹中

配置

iOS

将react-native-kf5sdk添加进工程的方法有两种：

通过rnpm link,

如果你还没有安装rnpm，执行以下命令来安装rnpm

npm install -g rnpm

安装完rnpm后执行以下命令,link成功命令行会提示'rnpm-link info Linking react-native-kf5sdk ios dependency'

rnpm link react-native-kf5sdk

或者你还可以手动配置

a.打开XCode's工程中, 右键点击Libraries文件夹 ➜ Add Files to <...> 
b.去node_modules ➜ react-native-kf5sdk ➜ ios ➜ 选择 RCTKF5SDK.xcodeproj 
c.在工程Build Phases ➜ Link Binary With Libraries中添加libRCTKF5SDK.a

工程配置

一、添加需要的系统依赖库

在工程target的Build Phases->Link Binary with Libraries中加入libsqlite3.tbd、JavaScriptCore.framework、Photos.framework、AssetsLibrary.framework等依赖库

二、SDK需要使用以下权限,进入工程中的info.plist，添加以下权限

Privacy - Camera Usage Description：我们需要拍摄照片发送图片,是否允许打开相机？
Privacy - Microphone Usage Description：我们需要录音发送语音消息,是否允许开启麦克风?
Privacy - Photo Library Usage Description：我们需要为您展示图片列表,是否允许访问媒体资料库？

三、需要将RCTKF5SDK/Bundle加入到工程里

RCTKF5SDK/Bundle是kf5sdk中需要使用的图片资源和国际化资源

四、如果在原生代码中需要引入KF5SDK

在工程target的Build Setting->Library Search Paths中添加$(SRCROOT)/../node_modules/react-native-kf5sdk/ios/RCTKF5SDK,在Header Search Paths中添加$(SRCROOT)/../node_modules/react-native-kf5sdk/ios/RCTKF5SDK

提醒事项

如果运行react-native run-ios提示类似错误信息undefined is not an object (evaluating 'kf5sdk.init.KF5')，请详细确认工程配置的第一、二、三步是否有遗漏，如果没有遗漏还是出现这个提示，请直接使用xcode运行工程，查看具体的报错信息，将报错信息完整截图后，提交Issues，我们将协助您处理。

Android

手动配置

一、编辑android/settings.gradle

// ...
include ':app'
include ':react-native-kf5sdk'
project(':react-native-kf5sdk').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-kf5sdk/android')

二、编辑android/app/build.gradle

// ...

dependencies {
    // ...
    compile project(':react-native-kf5sdk')
}

三、在MainApplication.java中注册模块（基于React-Native 0.32+）

编辑android/app/src/main/java/.../MainApplication.java

// ...

import com.kf5.rn.KF5SdkPackage;    // <--- 导包

public class MainApplication extends Application implements ReactApplication {
    // ...

    private final ReactNativeHost mReactNativeHost = new ReactNativeHost(this) {
        // ...

        @Override
        protected List<ReactPackage> getPackages() {
            return Arrays.<ReactPackage>asList(
                new MainReactPackage(),
                new KF5SdkPackage()
            );
        }

        // ...
    };

    // ...
}

如果你使用的React-Native版本中不包含MainApplication.java，则可能需要在MainActivity.java中注册模块，方法同上。

三、方法接口描述

react-native-kf5sdk提供一下方法：

• initKF5
• showHelpCenter
• showRequestCreation
• showRequestList
• showChatView
• setCustomFields
• setTopBarColor

* initKF5

初始化kf5

initKF5({params}, callback(result)) 

params

callback(result)

示例代码

import kf5sdk from 'react-native-kf5sdk';

var param = {  
    hostName : "xxx.kf5.com",  
    appId : "xxxxxxx",
    appName : "iOSAPP",
    email : "",  
    phone : "",
    verifyUserType : 1,
    deviceToken : "",
    userName : "",
};  
kf5sdk.initKF5(param, callback);

callback(result) {
    Alert.alert(result.message);
}

补充说明

使用此模块，必须先用initKF5进行初始化，初始化之前无法使用此模块的其他方法。手机和邮箱必须格式正确。

1.email和phone必须传其一,如果单独传入email或者phone,则verifyUserType无效;
2.如果email和phone都传入时以verifyPriorityType(用户信息验证方式)为主;

2.1 如果verifyUserType设置为1,则验证kf5系统中有没有该email,有则验证成功,并修改该用户的手机号(如果手机号已在系统中存在,将不会修改);
2.2 如果verifyUserType设置为2,则验证kf5系统中有没有该phone,有则验证成功;

2.2.1 如果该用户不存在email则添加该email(如果该email已在系统中存在,将不会添加);
2.2.1 如果该用户存在email,则email不能修改;

* showHelpCenter

弹出kf5帮助文档页面

showHelpCenter({params})  

params

示例代码

import kf5sdk from 'react-native-kf5sdk';

var params = {
    type: 0
};
kf5sdk.showHelpCenter(params);  

补充说明

使用此接口,必须先使用initKF5进行初始化。

* showRequestCreation

弹出kf5反馈问题页面

showRequestCreation()  

示例代码

import kf5sdk from 'react-native-kf5sdk';

kf5sdk.showRequestCreation();  

补充说明

使用此接口，必须先使用initKF5进行初始化。 使用此接口需添加相机和照片的权限。

* showRequestList

弹出kf5查看反馈页面

showRequestList() 

示例代码

import kf5sdk from 'react-native-kf5sdk';

kf5sdk.showRequestList();  

补充说明

使用此接口，必须先使用initKF5进行初始化。

* showChatView

弹出kf5即时交谈

showChatView({params})

params

示例代码

import kf5sdk from 'react-native-kf5sdk';

var params = {
    metadata  : [
        {
            "name":"姓名",
            "value":"小明"
        },
        {
            "name":"性别",
            "value":"男"
        }
    ],
}; 
kf5sdk.showChatView(params);  

补充说明

使用此接口，必须先使用initKF5进行初始化。 使用此接口需添加相机、麦克风和照片的权限。

* setCustomFields

设置工单自定义字段

setCustomFields({params})

params

示例代码

import kf5sdk from 'react-native-kf5sdk';

var params = {
	custom_fields : [
		{
			"name" : "fields_123",
			"value" : "iOS"
		}, 
		{
			"name" : "fields_321",
			"value" : "测试应用"
		}
	]
};
kf5sdk.setCustomFields(params);  

补充说明

使用此接口，需配合工单模块一起使用。工单自定义字段的key在kf5后台的设置工单自定义字段里获取。

* setTopBarColor

设置头部nav的颜色样式

setTopBarColor({params})  

params

示例代码

import kf5sdk from 'react-native-kf5sdk';

var params = {
    navColor: "#3E4245",
    textColor: "#FFFFFF",
    centerTextSize: 22,
    rightTextSize: 20,
    centerTextVisible: true,
    rightTextVisible: true,
};
kf5sdk.setTopBarColor(params);

补充说明

使用此接口，需配合其他接口一起使用。

四、推送设置

云客服移动SDK 通知普通用户工单被客服公开回复，或即时交谈的离线消息。

目前集成推送通知的唯一方法是使用一个回调的API，在使用该API前，您必须保证您的应用开启了远程推送服务。

在这里，你需要做三件事： 1、 在你的账号里配置您的移动SDK应用程序启动推送通知 2、 设置回调URL支持我们的回调 3、 在您的应用程序处理用户的唯一标示和推送请求

回调的API

当有消息发送时，云客服SDK将通知您设置的回调URL。之后，您的服务必须处理发送推送通知到最终用户的设备。 当我们想要发送一个通知给最终用户,我们会发送一个流请求的URI设置应用程序配置。示例请求:

 <回调URL>
Content-Type: application/json
Accept: application/json
{
  // 用户的信息 object
  "user":{
      // 被推送的user_id inter
      "user_id":123
    },
  // 设备的列表 array
  "device":[{ 
      // 设备的唯一标示 string
      "device_token":"1234567890",
      // 设备的类型 string IOS 或 Android
      "type":"IOS"
  }],
  // 推送通知信息 object
  "notification": {
    // 工单的id
    "ticket_id":"123",
    // 类型
    "type":"ticket"
  }
}

同样，在聊天中发送离线消息中，向设置的回调URL发送的数据示例:

 <回调URL>
Content-Type: application/json
Accept: application/json
{
  // 用户的信息 object
  "user":{
      // 被推送的user_id inter
      "user_id":123
    },
  // 设备的列表 array
  "device":[{
      // 设备的唯一标示 string
      "device_token":"1234567890",
      // 设备的类型 string IOS 或 Android
       "type":"IOS"
  }],
  // 推送通知信息 object
  "notification": {
      // 聊天消息
      "message":"hello",
      // 类型
      "type":"im"
  }
}