安卓SDK 4.x 开发指南

九五在线客服致力于为开发者提供极致用户体验的多渠道在线客服系统,包括 App、微信、web/h5等. 去注册。

一. 创建App

  1. 登录 管理后台,到 我的应用 页面,点击 创建应用 并保存
  2. App创建成功后,获取 Appkey, 填写到应用的AndroidManifest.xml文件相应位置, 具体可参加Demo中的AndroidManifest.xml文件
  3. 创建工作组, 并将相应的客服工作组ID填写到 App 中相应的位置(接口KFAPIs.startChat中参数)
  4. 分配客服,使用分配的客服账号登录 PC客服端下载

说明:在新的应用创建过程中,请尽量填写准确的信息,便于我们为您提供更加周到的服务

二. 下载SDK

在这里 SDK下载, 内含Demo程序和jar包, Android SDK支持发送 文字、表情、图片、语音
_images/android_1.png _images/android_2.png _images/android_3.png _images/android_4.png

三. 开发步骤

  1. 导入im95ykf_android_sdk_v4.jar

    直接将SDK/im95ykf_android_sdk_v4.jar文件拷贝到项目工程libs文件夹下面

  2. 添加资源res文件

    将下载的 “SDK/res”文件夹中的资源,拷贝到您的项目的”res”文件夹中,其中:SDK中的资源文件均以“appkefu”开头

  3. 配置AndroidManifest.xml

    请将下列 权限(user-permission)/Activity/Service/receivers分别拷贝到AndroidManifest.xml的相应位置

    注意:请替换自己申请的appkey

      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    <manifest……>......
           <!-- 聊天界面拍照发送图片 -->
           <uses-permission android:name="android.permission.CAMERA" />
           <!-- 登录接口:检测/监听网络状态 -->
           <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
           <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
           <!-- 登录接口:访问网络,连接im服务器 -->
           <uses-permission android:name="android.permission.INTERNET" />
           <!-- 聊天:收到消息后震动 -->
           <uses-permission android:name="android.permission.VIBRATE" />
           <!-- 聊天界面:录制语音,将语音文件保存在手机内存卡,检测是否已经装载文件系统 -->
           <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
           <uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS" />
           <uses-permission android:name="android.permission.RECORD_AUDIO" />
           <!-- 后台收到消息的时候,休眠状态唤醒CPU,将消息显示在通知栏 -->
           <uses-permission android:name="android.permission.WAKE_LOCK" />
           <!-- 可选:监听手机重启自动重连服务器 -->
           <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
           <application ...>
           ……
           <!-- 请到 http://im.95ykf.com/AppKeFu/admin/ 申请appkey-->
           <meta-data
                   android:name="com.appkefu.lib.appkey"
                   android:value="6f8103225b6ca0cfec048ecc8702dbce" />
           <!-- 聊天窗口, 可通过修改layout文件appkefu_activity_kfvip_chat.xml自定义窗口UI -->
           <activity android:name="com.appkefu.lib.ui.activity.KFChatActivity"
                   android:theme="@style/appkefu_theme_no_titlebar"
                   android:configChanges="orientation|keyboardHidden|screenSize"/>
           <!-- 设置页面,点击聊天窗口右上角按钮进入,可清空聊天记录 -->
           <activity android:name="com.appkefu.lib.ui.activity.KFSettingsActivity"
           android:theme="@style/appkefu_theme_no_titlebar" />
           <!-- 常见问题类别页面,点击聊天页面输入框下方扩展面板:常见问题按钮进入 -->
           <activity android:name="com.appkefu.lib.ui.activity.KFFAQActivity"
           android:theme="@style/appkefu_theme_no_titlebar"/>
           <!-- 常见问题详情页面, -->
           <activity android:name="com.appkefu.lib.ui.activity.KFFAQDetailActivity"
           android:theme="@style/appkefu_theme_no_titlebar"/>
           <!-- 满意度评价页面 -->
           <activity android:name="com.appkefu.lib.ui.activity.KFRateActivity"
           android:theme="@style/appkefu_theme_no_titlebar"/>
           <!-- 留言页面 -->
           <activity android:name="com.appkefu.lib.ui.activity.KFLeaveMessageActivity"
           android:theme="@style/appkefu_theme_no_titlebar"/>
           <!-- 内嵌浏览器页面,打开网址 -->
           <activity android:name="com.appkefu.lib.ui.activity.KFWebBrowserActivity"
           android:theme="@style/appkefu_theme_no_titlebar">
                   <intent-filter>
                           <action android:name="android.intent.action.VIEW" />
                           <category android:name="android.intent.category.DEFAULT" />
                           <category android:name="android.intent.category.BROWSABLE" />
                           <!-- 此处data的android:scheme请填写您App的包名,保持android:host, 如下所示: -->
                           <data android:scheme="com.appkefu.demo2" android:host="appkefu_url" />
                   </intent-filter>
           </activity>
           <!-- 发送语音辅助service -->
           <service android:name="com.appkefu.lib.soundrecorder.KFRecorderService"/>
           <!-- im长连接 主service -->
           <service android:name="com.appkefu.lib.service.KFMainService">
                   <intent-filter android:priority="1000">
                           <!-- 可选 android:priority = "1000"这个属性设置最高优先级,1000是最高值,如果数字越小则优先级越低 -->
                           <action android:name="com.appkefu.lib.action.kefu.LOGIN_WITH_OPENUDID"/>
                           <action android:name="com.appkefu.lib.action.DISCONNECT" />
                           <action android:name="com.appkefu.lib.action.TOGGLE" />
                           <action android:name="com.appkefu.lib.action.SEND" />
                           <action android:name="com.appkefu.lib.action.NETWORK_STATUS_CHANGED" />
                           <action android:name="com.appkefu.lib.action.XMPP.MESSAGE_RECEIVED" />
                   </intent-filter>
           </service>
           <!-- 获取OpenUDID, 用于唯一标示用户 -->
           <service android:name="com.appkefu.OpenUDID.OpenUDID_service" >
                   <intent-filter>
                           <action android:name="org.openudid.GETUDID" />
                   </intent-filter>
           </service>
           <!-- 可选:监听网络变化 -->
           <receiver android:name="com.appkefu.lib.receivers.KFNetworkConnectivityReceiver" >
                   <intent-filter>
                           <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
                   </intent-filter>
           </receiver>
           <!-- 可选:监听手机重启,方便重连im服务器, 需要配合权限RECEIVE_BOOT_COMPLETED使用-->
           <receiver android:name="com.appkefu.lib.receivers.KFBootReceiver" >
                   <intent-filter>
                           <action android:name="android.intent.action.BOOT_COMPLETED" />
                           <category android:name="android.intent.category.HOME" />
                   </intent-filter>
           </receiver>
           <!-- 可选:监听手机连接电源状态,如果已经连接电源自动尝试重连 -->
           <receiver android:name="com.appkefu.lib.receivers.KFPowerReceiver" >
                   <intent-filter>
                           <action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
                           <action android:name="android.intent.action.ACTION_POWER_DISCONNECTED" />
                   </intent-filter>
           </receiver>
           <!-- 监听客服发送过来的消息 -->
           <receiver android:name="com.appkefu.lib.receivers.KFMessageReceiver">
                   <intent-filter>
                           <action android:name="com.appkefu.lib.action.XMPP.MESSAGE_RECEIVED" />
                   </intent-filter>
           </receiver>
           <!-- 可选:检测屏幕是否解锁,以便重连服务器 -->
           <receiver android:name="com.appkefu.lib.receivers.KFScreenReceiver">
                   <intent-filter>
                           <action android:name="android.intent.action.USER_PRESENT" /><!-- 监听屏幕解锁 -->
                   </intent-filter>
           </receiver>
           <!-- 定时检测是否需要重连im服务器,以便重连服务器 -->
           <receiver android:name="com.appkefu.lib.receivers.KFAlarmReceiver">
                   <intent-filter>
                           <action android:name="com.appkefu.lib.action.LOGIN_ALARM" />
                   </intent-filter>
           </receiver>
           </application>
           ......
    </manifest>
    
  4. 客服Demo讲解

    1. 登录,在onCreate()里面添加

       1
       2
       3
       4
       5
       6
       7
       8
       9
      10
      11
      protected void onCreate(Bundle savedInstanceState) {
              super.onCreate(savedInstanceState);
              setContentView(R.layout.activity_main);
              //第一步:登录
              //第一种登录方式,推荐
              //注意:需要调用标签接口设置昵称,否则在客服端看到的会是一串字符串
              KFAPIs.visitorLogin(this);
      }
      
    2. 监听通知:添加receiver

       1
       2
       3
       4
       5
       6
       7
       8
       9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      //监听:连接状态、即时通讯消息、客服在线状态
      private BroadcastReceiver mXmppreceiver = new BroadcastReceiver() {
              public void onReceive(Context context, Intent intent) {
                      String action = intent.getAction();
                      //监听:连接状态
                      if (action.equals(KFMainService.ACTION_XMPP_CONNECTION_CHANGED))//监听链接状态{
                              updateStatus(intent.getIntExtra("new_state", 0));
                      }
              //监听:即时通讯消息
                      else if(action.equals(KFMainService.ACTION_XMPP_MESSAGE_RECEIVED))//监听消息
                      {
                              String body = intent.getStringExtra("body");
                              String from = StringUtils.parseName(intent.getStringExtra("from"));
                              KFLog.d("body:"+body+" from:"+from);
                      }
              }
              //客服工作组在线状态
              else if(action.equals(KFMainService.ACTION_XMPP_WORKGROUP_ONLINESTATUS))
              {
                      String onlineStatus = intent.getStringExtra("onlinestatus");
                      KFLog.d("客服工作组:"+ onlineStatus);//online:在线;offline: 离线
                      if(onlineStatus.equals("online"))
                      {       KFLog.d("online");}
                      else
                      {KFLog.d("offline");}
              }
      };
      
    3. 注册和销毁receiver,分别在onStart()和onStop()里面

       1
       2
       3
       4
       5
       6
       7
       8
       9
      10
      11
      12
      13
      14
      15
      16
      17
      protected void onStart() {
              super.onStart();
              IntentFilter intentFilter = new IntentFilter();
              //监听网络连接变化情况
              intentFilter.addAction(KFMainService.ACTION_XMPP_CONNECTION_CHANGED);
              //监听消息
              intentFilter.addAction(KFMainService.ACTION_XMPP_MESSAGE_RECEIVED);
              //工作组在线状态
              intentFilter.addAction(KFMainService.ACTION_XMPP_WORKGROUP_ONLINESTATUS);
                      registerReceiver(mXmppreceiver, intentFilter);
              }
              @Override
              protected void onStop() {
                  super.onStop();
                  if(mXmppreceiver != null){
                      unregisterReceiver(mXmppreceiver);
                  }
              }
      }
      
    4. 另外,还有重要登录状态函数

       1
       2
       3
       4
       5
       6
       7
       8
       9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      //根据监听到的连接变化情况更新界面显示
      private void updateStatus(int status) {
      switch (status) {
              case KFXmppManager.CONNECTED:
                      mTitle.setText("九五在线客服(Demo)");
                      //在成功建立连接之后, 查询客服工作组在线状态,返回结果在BroadcastReceiver中返回
                      KFAPIs.checkKeFuIsOnlineAsync("comId","wgdemo", this);
                      break;
              case KFXmppManager.DISCONNECTED:
                      mTitle.setText("九五在线客服(Demo)(未连接)");
                      break;
              case KFXmppManager.CONNECTING:
                      mTitle.setText("九五在线客服(Demo)(登录中...)");
                      break;
              case KFXmppManager.DISCONNECTING:
                      mTitle.setText("九五在线客服(Demo)(登出中...)");
                      break;
              case KFXmppManager.WAITING_TO_CONNECT:
              case KFXmppManager.WAITING_FOR_NETWORK:
                      mTitle.setText("九五在线客服(Demo)(登录中)");
                      break;
              default:throw new IllegalStateException();
              }
      }
      
    5. 检测客服在线状态

      1
      2
      3
      //查询客服工作组在线状态,返回结果在BroadcastReceiver中返回
      KFAPIs.checkKeFuIsOnlineAsync("comId","wgdemo", //注意:此处应该填写 企业ID,工作组 名称,体参见第一步
      this);
      
    6. 发起会话

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    //1.咨询客服
    KFAPIs.startChat(this,
           "comId",       //1. 企业ID(请务必保证大小写一致),请在管理后台查看
           "wgdemo",       //2. 客服工作组名称(请务必保证大小写一致),请在管理后台分配
           "客服小秘书",        //3. 会话界面标题,可自定义
           "订单信息", //4. 附加信息,在成功对接客服之后,会自动将此信息发送给客服;
           //   如果不想发送此信息,可以将此信息设置为""或者null
           true,   //5. 是否显示自定义菜单,如果设置为显示,请务必首先在管理后台设置自定义菜单,
           //      请务必至少分配三个且只分配三个自定义菜单,多于三个的暂时将不予显示
           //      显示:true, 不显示:false
           5,      //6. 默认显示消息数量
           //修改SDK自带的头像有两种方式,1.直接替换appkefu_message_toitem和appkefu_message_fromitem.xml里面的头像,2.传递网络图片url网址
           "http://114.215.189.207/PHP/XMPP/gyfd/chat/web/img/kefu-avatar.png",            //7. 修改默认客服头像,如果不想修改默认头像,设置此参数为null
           "http://114.215.189.207/PHP/XMPP/gyfd/chat/web/img/user-avatar.png",            //8. 修改默认用户头像, 如果不想修改默认头像,设置此参数为null
           false,  //9. 默认机器人应答
           new KFCallBack() {      //10. 会话页面右上角回调函数
           /*** 11.是否使用对话界面右上角默认动作. 使用默认动作返回:true, 否则返回false*/
           @Override
           public Boolean useTopRightBtnDefaultAction() {
                   return true;
           }
           /*** 12.点击对话界面右上角按钮动作,依赖于 上面一个函数的返回结果*/
           @Override
           public void OnChatActivityTopRightButtonClicked() {
           // TODO Auto-generated method stub
                   Log.d("KFMainActivity", "右上角回调接口调用");
                   Toast.makeText(KFMainActivity.this, "右上角回调接口调用", Toast.LENGTH_SHORT).show();
           }
           /*** 13.点击商品详情图片回调函数*/
           @Override
           public void OnECGoodsImageViewClicked(String imageViewURL) {
                   // TODO Auto-generated method stub
                   Log.d("KFMainActivity", "OnECGoodsImageViewClicked"+imageViewURL);
           }
           /*** 14.点击商品详情简介回调函数*/
           @Override
           public void OnECGoodsTitleDetailClicked(String titleDetailString) {
                   // TODO Auto-generated method stub
                   Log.d("KFMainActivity", "OnECGoodsIntroductionClicked"+titleDetailString);
           }
           /*** 15.点击商品详情价格回调函数*/
           @Override
           public void OnECGoodsPriceClicked(String priceString) {
                   // TODO Auto-generated method stub
                    Log.d("KFMainActivity", "OnECGoodsPriceClicked"+priceString);
           }
           /*** 16.点击商品详情布局回调函数*/
           @Override
           public void OnEcGoodsInfoClicked(String callbackId) {
                   // TODO Auto-generated method stub
                   Log.d("KFMainActivity", "OnEcGoodsInfoClicked"+callbackId);
           }
    });
    
  5. 常见问题FAQ模块

    此模块位于SDK会话页面,其中的内容需要在 管理后台 添加

    1. 进入工作组详情页面
    2. 找到常见问题类别模块
    3. 首先添加常见问题类别,然后为每个类别添加常见问题
  6. 自定义菜单

    后台随时设定自定义菜单,方便用户通过SDK内嵌的浏览器跳转到指定的网页,为用户提供更加便捷的服务

    1. 在管理后台“工作组详情”页面创建 自定义菜单
    2. 在SDK设置相应的参数,具体参见 6.发起会话
  7. 机器人自动应答

    通过 管理后台 添加机器人自动应答问题,可以有效的提高客服的工作效率

    1. 在管理后台“工作组详情”页面找到“机器人自动应答”
    2. 添加相应的问题和答案
  8. 自定义客服和用户头像

    修改会话页面的客服头像和用户头像有两种方式,1.使用本地图片静态替换;或者 2.使用网络图片动态替换

    1. 使用第一种方式客服直接找到资源文件res/layout/appkefu_message_toitem.xml(用户发送消息布局)和appkefu_message_fromitem.xml(客服发送消息布局)找到相应的imageview直接替换android:src即可
    2. 直接将客服头像和用户头像网址传递到相应参数即可
  9. 自定义通知栏样式

    可以通过修改res/layout/appkefu_notification_contentview.xml自定义通知布局修改

    1. 通知栏icon
    2. 是否显示具体消息内容
    3. 自定义其他颜色样式等
    4. 通过替换res/drawable-hdpi/appkefu_notification_icon.png图片自定义通知栏icon
    5. 通过显示或者隐藏布局中的TextView来调整是否显示具体消息内容

四. 自定义会话界面

开发者可以根据自己需要自定义界面显示格式

  1. appkefu_activity_kfvip_chat.xml 会话主界面
  2. appkefu_message_fromitem.xml 来自客服的会话内容
  3. appkefu_message_toitem.xml 用户自己发送的会话内容
  4. appkefu_activity_kfsettings.xml 设置界面
  5. appkefu_notification_contentview.xml 通知栏布局
  6. appkefu_activity_kffaq.xml 常见问题布局
  7. appkefu_activity_kffaqdetail.xml 常见问题详情布局

五. 混淆

Proguard:

  1. -dontwarn com.appkefu.**
  2. -keep class com.appkefu.** { *;}

为app的R文件单独增加一条keep,比如您的app的package为com.example.kefutest2,则增加如下:

  1. -keep class com.example.kefutest2.R$* { *;}

六. API接口

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
//登录
KFAPIs.visitorLogin(Context context)
        //检测客服在线状态
        //comId: 企业ID
        //workgroupName: 工作组名称
        //context: 上下文
KFAPIs.checkKeFuIsOnlineAsync(String comId,String workgroupName,Context context)
        /**
        *
        * @param context                       上下文
        * @param comId                    企业ID(请务必保证与管理后台分配的名称大小写一致),请在管理后台查看
        * @param workgroupName            客服工作组名称(请务必保证与管理后台分配的名称大小写一致),请在管理后台分配
        * @param title                         会话界面标题,可自定义
        * @param productInfo            附加信息,在成功对接客服之后,会自动将此信息发送给客服; 如果不想发送此信息,可以将此信息设置为""或者null
        * @param showMenu                       是否显示自定义菜单,如果设置为显示,请务必首先在管理后台设置自定义菜单,
        请务必至少分配三个且只分配三个自定义菜单,多于三个的暂时将不予显示
        显示:true, 不显示:false
        * @param showMessageCount  默认显示的消息记录的数量
        * @param kefuAvatarURL         客服头像网络URL地址
        * @param userAvatarURL         用户图像网络URL地址
        * @param defaultRobot          是否默认进入机器人应答,true:是;false:否
        * @param mustRateBoolean       用户在关闭对话的时候是否强制满意度评价, true:是; false:否
        * @param callBack                      回调接口
        */
public static void startChat(Context context
        ,String comId
        ,String workgroupName
        ,String title
        ,String productInfo
        ,Boolean showMenu
        ,int showMessageCount
        ,String kefuAvatarURL
        ,String userAvatarURL
        ,Boolean defaultRobot
        ,Boolean mustRateBoolean
        ,KFCallBack callBack);
       /***
        * @param context                       上下文
        * @param comId                    企业ID(请务必保证与管理后台分配的名称大小写一致),请在管理后台查看
        * @param workgroupName            客服工作组名称(请务必保证与管理后台分配的名称大小写一致),请在管理后台分配
        * @param title                         会话界面标题,可自定义
        * @param productInfo            附加信息,在成功对接客服之后,会自动将此信息发送给客服; 如果不想发送此信息,可以将此信息设置为""或者null
        * @param showMenu                       是否显示自定义菜单,如果设置为显示,请务必首先在管理后台设置自定义菜单,
        请务必至少分配三个且只分配三个自定义菜单,多于三个的暂时将不予显示
        显示:true, 不显示:false
        * @param showMessageCount  默认显示的消息记录的数量
        * @param kefuAvatarURL         客服头像网络URL地址
        * @param userAvatarURL         用户图像网络URL地址
        * @param defaultRobot          是否默认进入机器人应答,true:是;false:否
        * @param showGoodsLayout       是否显示商品详情布局
        * @param goodsImageViewURL     商品详情图片
        * @param goodsTitleDetail      商品详情标题
        * @param goodsPrice            商品详情价格
        * @param goodsCallbackID       点击商品详情布局回调ID
        * @param mustRateBoolean       用户在关闭对话的时候是否强制满意度评价, true:是; false:否
        * @param callBack                      回调接口*/
public static void startECChat(Context context
        ,String comId
        ,String workgroupName
        ,String title
        ,String productInfo
        ,Boolean showMenu
        ,int showMessageCount
        ,String kefuAvatarURL
        ,String userAvatarURL
        ,Boolean defaultRobot
        ,Boolean showGoodsLayout
        ,String goodsImageViewURL
        ,String goodsTitleDetail
        ,String goodsPrice
        ,String goodsWeburl
        ,String goodsCallbackID
        ,Boolean mustRateBoolean
        ,KFCallBack callBack);

/**
       * 打开常见问题FAQ
       * @param context
       * @param comId         企业ID
       * @param workgroupName 工作组ID
*/
KFAPIs.showFAQ(Context context, String comId,String workgroupName)
/**
       * 获取用户标签
       * @return
*/
public static KFUserTagsEntity getTags(Context context)
//设置昵称
KFAPIs.setTagNickname(String nickname,Context context)
//设置性别
KFAPIs.setTagSex(String sex,Context context)
//设置语言
KFAPIs.setTagLanguage(String language,Context context)
//设置所在城市
KFAPIs.setTagCity(String city,Context context)
//设置所在省份
KFAPIs.setTagProvince(String province,Context context)
//设置所在国家
KFAPIs.setTagCountry(String country,Context context)
//设置自定义标签
KFAPIs.setTagOther(String othe,Context contextr)
//退出登录
KFAPIs.Logout(Context context)

七. 其他

更新日期:2017/03/31