移动客服 Android SDK 集成

移动客服现已推出专属 Android SDK!您只需在移动客服系统创建 APP 关联,并按照本文档的步骤集成 Android SDK,即可轻松实现 Android 版 APP 接入。

移动客服 Android SDK 已集成双通道功能,确保不丢消息;并提供会话相关内置 UI,集成移动客服通用功能,只需5分钟。

Android SDK 支持以下功能:

  • 发送文本消息、语音消息、图片消息、文件消息。
  • 接收文本消息、语音消息、图片消息、文件消息、机器人菜单消息。
  • 显示客服头像和昵称、显示机器人转人工按钮。
  • 显示访客信息,指定客服,指定技能组(参考第4步:集成更多业务功能)。
  • 支持留言功能,包括文字、图片和语音留言(参考第5步:集成更多扩展功能)。

第1步:快速创建APP关联

移动客服系统的“APP关联”对应即时通讯云(IM)后台的应用。在移动客服系统创建关联后,可直接登录IM后台管理该关联对应的应用。

  • 如果您还没有环信即时通讯云的账号,可以打开环信移动客服,进入“管理员模式 > 渠道管理 > 手机APP”,快速创建一个“APP关联”;
  • 如果您已有环信即时通讯云的账号,并创建了应用,可以登录环信移动客服,进入“管理员模式 > 渠道管理 > 手机APP”,关联您的IM账号。

关于快速创建APP关联的分步骤演示,请参考:快速创建APP关联

第2步:环境准备

开发工具:Android Studio。

集成移动客服Android SDK时,可参考“商城”demo源码和EaseUI源码。

下载地址:https://github.com/easemob/kefu-android-demo

KefuSDK基于IMSDK3.x,如同时使用环信IM功能(非音视频),需使用此文档中的初始化、登录、登出操作,不需要添加IM的SDK,其IM SDK-API正常使用。

第3步:集成 Android SDK

移动客服Android SDK已包含EaseUI,完成该步骤可以实现用户注册、登录、退出,向移动客服系统发送文本、语音、图片、文件消息功能。

注意事项

  1. 自定义的Application需要在Androidmanifest.xml中注册;
  2. 切记,先判断登录状态再进入会话界面,否则会出问题,检测登录状态的方法:ChatClient.getInstance().isLoggedInBefore()

build.gradle 配置

添加移动客服SDK及其他依赖。

在app的 build.gradle 文件的defaultConfig和dependencies中加入如下(添加后需同步gradle):

android{
   ......
   defaultConfig {
     ndk {
        //选择要添加的对应cpu类型的.so库
        abiFilters 'armeabi', 'arm64-v8a'
        //还可以添加 'armeabi-v7a', 'x86'
     }
   }
}

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    //环信客服SDK
    compile 'com.hyphenate:kefu-easeui-android:latest.release' //或者 compile 'com.hyphenate:kefu-easeui-android:1.0.4'
    //EaseUI中 头像获取用到了glide,请添加glide库
    compile 'com.github.bumptech.glide:glide:3.7.0' //其他版本也可以
    //EaseUI中,fragment用到了android-support-v4包
    compile 'com.android.support:support-v4:23.1.1' //其他版本也可以
}

注意:如果在添加以上abiFilter配置后AndroidStudio有如下提示:

NDK integration is deprecated in the current plugin. Consider trying the new experimental plugin.

则需要在Project根目录的gradle.properties文件中添加:

android.useDeprecatedNdk=true

初始化

移动客服Android SDK包含EaseUI,需要在Application中调用初始化的方法(本示例中Application的文件名为MyApplication.java):

  • 使用ChatClient方法对SDK进行初始化
  • 使用UIProvider方法对EaseUI进行初始化

ChatClient的其他方法也都需要在它后面调用。例如:本文档中的DebugMode(日志),以及Demo中的自定义通知栏、消息通知等。

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        ChatClient.Options options = new ChatClient.Options();
        options.setAppkey("Your appkey");//必填项,appkey获取地址:kefu.easemob.com,“管理员模式 > 渠道管理 > 手机APP”页面的关联的“AppKey”
        options.setTenantId("Your tenantId");//必填项,tenantId获取地址:kefu.easemob.com,“管理员模式 > 设置 > 企业信息”页面的“租户ID”
        
        // Kefu SDK 初始化
        if (!ChatClient.getInstance().init(this, options)){
            return;
        }
        // Kefu EaseUI的初始化
        UIProvider.getInstance().init(this);
        //后面可以设置其他属性
    }
}
//Kefu sdk 初始化简写方式:
  ChatClient.getInstance().init(this, new ChatClient.Options().setAppkey("zdxd#ksf").setTenantId("35"));

自定义的Application需要在Androidmanifest.xml中注册。

<application
        ...
        android:name=".MyApplication"
        ...
</application>

注册

注册模式分两种,开放注册和授权注册。只有开放注册时,才可以客户端注册。

  • 开放注册是为了测试使用,正式环境中不推荐使用该方式注册环信账号;
  • 授权注册的流程应该是您服务器通过环信提供的 REST API 注册,之后保存到您的服务器或返回给客户端。

建议使用授权模式,即在服务端注册,而不要放到APP中,可以在登录自己APP时从返回的结果中获取环信账号再登录环信服务器。

ChatClient.getInstance().createAccount("username", "password", new Callback(){});

//ErrorCode:
Error.NETWORK_ERROR 网络不可用
Error.USER_ALREADY_EXIST  用户已存在
Error.USER_AUTHENTICATION_FAILED 无开放注册权限(后台管理界面设置[开放|授权])
Error.USER_ILLEGAL_ARGUMENT 用户名非法

登录

用户需要登录后才能进入会话界面,与客服聊天。

ChatClient.getInstance().login("username", "password", new Callback(){});

登录状态

需要先判断登录状态再进入会话界面,否则会出问题。

if(ChatClient.getInstance().isLoggedInBefore()){
    //已经登录,可以直接进入会话界面
}else{
    //未登录,需要登录后,再进入会话界面
}

退出

登出后则无法收到客服发来的消息。

//第一个参数为是否解绑推送的devicetoken
ChatClient.getInstance().logout(true, new Callback(){});

日志

设置调试模式。

// 设置为true后,将打印日志到logcat, 发布APP时应关闭该选项
ChatClient.getInstance().setDebugMode(true|false);

会话

新建“联系客服”按钮,并调用以下方法打开会话界面。

注意:该方法中设置的“IM服务号”需要与初始化时设置的appkey对应。

Intent intent = new IntentBuilder({Activity}.this)
                        .setServiceIMNumber("客服关联的IM服务号") //获取地址:kefu.easemob.com,“管理员模式 > 渠道管理 > 手机APP”页面的关联的“IM服务号”
                        .build();
                startActivity(intent);

界面引用了环信IM的EaseUI,您可以对界面进行修改,使用指南见EaseUI 使用指南

网络监听

添加网络监听,可以显示当前是否连接服务器。

ChatClient.getInstance().addConnectionListener(new ChatClient.ConnectionListener() {
            @Override
            public void onConnected() {
                   //成功连接到服务器
            }

            @Override
            public void onDisconnected(int errorcode) {
               //errorcode的值
               //Error.USER_REMOVED 账号移除
               //Error.USER_LOGIN_ANOTHER_DEVICE 账号在其他地方登录
               //Error.USER_AUTHENTICATION_FAILED 账号密码错误
               //Error.USER_NOT_FOUND  账号找不到

            }
        });

消息监听

添加消息监听。

ChatClient.getInstance().getChat().addMessageListener(new ChatManager.MessageListener() {
            @Override
            public void onMessage(List<Message> list) {
                //收到普通消息
            }

            @Override
            public void onCmdMessage(List<Message> list) {
                 //收到命令消息,命令消息不存数据库,一般用来作为系统通知,例如留言评论更新,
                 //会话被客服接入,被转接,被关闭提醒
            }

            @Override
            public void onMessageStatusUpdate() {
            //消息的状态修改,一般可以用来刷新列表,显示最新的状态

            }

            @Override
            public void onMessageSent() {
            //发送消息后,会调用,可以在此刷新列表,显示最新的消息

            }
        });

添加华为推送

1. 申请推送证书并添加后台。

进入华为开发者后台,创建一个应用,完成后配置push权益。创建完成后,会自动生成AppId和AppSecret,进入环信管理后台,选择你的应用→选择推送证书→Huawei→新增证书。 证书名称为从华为后台拿到的APPID,证书密钥为:AppSecret,点击上传即可。

2. 配置 AndroidManifest.xml。

<manifest>
     <application>
    ...
    <!-- huawei push 第三方相关 :接收Push消息(注册、Push消息、Push连接状态、标签,LBS上报结果)广播  -->
        <receiver android:name="com.hyphenate.chat.EMHuaweiPushReceiver" >
            <intent-filter>
                <!-- 必须,用于接收token -->
                <action android:name="com.huawei.android.push.intent.REGISTRATION" />
                <!-- 必须,用于接收消息 -->
                <action android:name="com.huawei.android.push.intent.RECEIVE" />
            </intent-filter>
            />
            <meta-data android:name="CS_cloud_ablitity" android:value="successRateAnalytics"/>
        </receiver>
        <!-- PushSDK:PushSDK接收外部请求事件入口-->
        <receiver
            android:name="com.huawei.android.pushagent.PushEventReceiver"
            android:process=":pushservice" >
            <intent-filter>
                <action android:name="com.huawei.android.push.intent.REFRESH_PUSH_CHANNEL" />
                <action android:name="com.huawei.intent.action.PUSH" />
                <action android:name="com.huawei.intent.action.PUSH_ON" />
                <action android:name="com.huawei.android.push.PLUGIN" />
            </intent-filter>
        </receiver>
        <!-- PushSDK:Push服务-->
        <service
            android:name="com.huawei.android.pushagent.PushService"
            android:process=":pushservice" >
        </service>
    ...
    </application>
</mainfest>

3. 添加HwPush_SDK_V2705_nomap.jar到项目的libs文件夹中。

4. Application初始化中option配置。

ChatClient.Options options = new ChatClient.Options();
options.setAppkey("Your appkey");//appkey获取地址:console.easemob.com
options.setTenantId("Your tenantId");//tenantId获取地址:kefu.easemob.com
options.setHuaweiPushAppId("huawei appid");//appid从华为开发者平台获取
// Huanxin Kefu SDK 初始化
if (!ChatClient.getInstance().init(this, options)){
    return;
}
//后面可以设置其他属性

打包混淆

混淆添加到proguard-rules.pro中。

#环信客服
-keep class com.hyphenate.** {*;}
-dontwarn  com.hyphenate.**

#如添加华为push
# Huawei push
-keep class com.huawei.android.pushagent.** {*;}
-keep class com.huawei.android.pushselfshow.** {*;}
-keep class com.huawei.android.microkernel.** {*;}
-keep class com.baidu.mapapi.** {*;}
-keep class com.hianalytics.android.** {*;}
-dontwarn com.huawei.android.pushagent.**
-dontwarn com.huawei.android.pushselfshow.**
-dontwarn com.huawei.android.microkernel.**
-dontwarn com.github.mikephil.charting.data.**

恭喜您!您已完成移动客服 Android SDK 基础功能的集成,用户可以使用您的 APP 给移动客服系统发送文本、语音、图片、文件消息。

第4步:集成更多业务功能

完成该步骤可以实现将用户资料传递到移动客服系统,将用户发起的会话直接分配给客服或技能组。

访客属性

传访客属性到移动客服系统,将展示在“会话”面板的“资料”tab页。

Intent intent = new IntentBuilder(this)
                .setServiceIMNumber("ceshia")
                .setVisitorInfo(ContentFactory.createVisitorInfo(null)
                        .companyName("huanxin")
                        .email("abc@123.com")
                        .qq("12345")
                        .name("visitor_" + userName)
                        .nickName("nick_" + userName))
                .build();
  startActivity(intent);

指定客服

当用户点击“联系客服”按钮时,发起的会话直接分配给指定的客服。

Intent intent = new IntentBuilder(this)
                .setServiceIMNumber("ceshia")
                .setScheduleAgent(ContentFactory.createAgentIdentityInfo("zhangsan@qq.com")) //需填写正确的客服的邮箱地址
                .build();
  startActivity(intent)

指定技能组

当用户点击“联系客服”按钮时,发起的会话直接分配给指定的技能组。

Intent intent = new IntentBuilder(this)
                .setServiceIMNumber("ceshia")
                .setScheduleQueue(ContentFactory.createQueueIdentityInfo("shouqian")) //需填写正确的技能组名称
                .build();
startActivity(intent);

实时通话(实时视频)

实时通话分为视频通话和音频通话,与普通电话不同,它是基于网络的。

  • 监听呼入通话

通过注册相应 action 的 BroadcastReceiver 来监听呼叫过来的通话,接到广播后开发者可以调起 APP 里的通话 Activity。

IntentFilter callFilter = new IntentFilter(ChatClient.getInstance().callManager().getIncomingCallBroadcastAction());
registerReceiver(new CallReceiver(), callFilter);
private class CallReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        // 拨打方username
        String from = intent.getStringExtra("from");
        // call type
        String type = intent.getStringExtra("type");
                //跳转到通话页面

    }
}

更多实时音视频API请参考移动客服Android SDK API

第5步:集成更多扩展功能

更多扩展功能(发送轨迹消息、发送订单消息、留言相关功能等),请参考移动客服Android SDK API

“显示满意度评价邀请”功能可参考Android版商城demo集成。

SDK更新日志

版本更新信息请查看更新日志。

Android SDK(访客端) 更新日志