ScreenShot #

集成来鼓 SDK #

AndroidStudio #

// -------------------- 以下三个库是必须依赖的 okhttp 必须 3.5.0 或者更高版本 ----------------------------
implementation 'com.laigu:laigusdk:3.6.3'
implementation 'com.android.support:support-v4:23.1.1'
//    implementation 'androidx.legacy:legacy-support-v4:1.0.0' // androidx 使用
implementation 'com.squareup.okhttp3:okhttp:3.5.0'
// -------------------- 以上三个库是必须依赖的 okhttp 必须 3.5.0 或者更高版本 ----------------------------
// 目前支持常见的 4 种图片加载库，必须在下面四个图片加载库中选择一个添加依赖
implementation 'com.nostra13.universalimageloader:universal-image-loader:1.9.5'
//    implementation 'com.squareup.picasso:picasso:2.5.2'
//    implementation 'org.xutils:xutils:3.3.36'
//    implementation 'com.github.bumptech.glide:glide:4.9.0'
//    annotationProcessor 'com.github.bumptech.glide:compiler:4.9.0'

使用来鼓 #

1.初始化 #

LGConfig.init(this, "Your Appkey", new OnInitCallback() {
    @Override
    public void onSuccess(String clientId) {
        Toast.makeText(MainActivity.this, "init success", Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onFailure(int code, String message) {
        Toast.makeText(MainActivity.this, "int failure", Toast.LENGTH_SHORT).show();
    }
});

2.启动对话界面 #

初始化成功后，就可以直接启动对话界面

使用当前 id 分配上线

Intent intent = new LGIntentBuilder(this).build();
startActivity(intent);

3.启动留言表单界面 #

目前是两种模式：

(1) 完全对话模式 无机器人时：如果当前客服不在线，直接聊天界面输入就是留言，客服上线后能够直接回复，如果客服在线，则进入正常客服对话模式。 有机器人时：如果当前客服不在线时，直接聊天界面输入的话，还是由机器人回答，顾客点击留言就会跳转到表单。

(2) 单一表单模式 不管客服是否在线都会进入表单，顾客提交后，不会有聊天的界面。这种主要用于一些 App 只需要用户反馈，不需要直接回复的形式。

startActivity(new Intent(this, LGMessageFormActivity.class));

常见使用场景 #

开发者的 App 有自己的账号系统，希望每个账号对应不同的顾客，有不同的聊天记录。那就需要开发者在启动对话的时候，绑定账号：

Intent intent = new LGIntentBuilder(this)
        .setCustomizedId("开发者的 id") // 相同的 id 会被识别为同一个顾客
        .build();
startActivity(intent);

开发者希望顾客上线的时候，能够上传（或者更新）一些用户的自定义信息：

HashMap<String, String> clientInfo = new HashMap<>();
clientInfo.put("name", "富坚义博");
clientInfo.put("avatar", "https://cdn.nlark.com/yuque/0/2019/jpeg/anonymous/1547086416118-8460ca70-f218-486b-aa5d-b8be073a242f.jpeg?x-oss-process=image%2Fresize%2Cm_fill%2Cw_48%2Ch_48%2Fformat%2Cpng");
clientInfo.put("gender", "男");
clientInfo.put("tel", "1300000000");
clientInfo.put("技能1", "休刊");

HashMap<String, String> updateInfo = new HashMap<>();
updateInfo.put("name", "update name");

Intent intent = new LGIntentBuilder(this)
        .setClientInfo(clientInfo) // 设置顾客信息 PS: 这个接口只会生效一次,如果需要更新顾客信息,需要调用更新接口
//      .updateClientInfo(updateInfo) // 更新顾客信息 PS: 如果客服在工作台更改了顾客信息，更新接口会覆盖之前的内容
        .build();
startActivity(intent);

指定客服分配

Intent intent = new LGIntentBuilder(this)
        .setScheduledAgent(agentId) // agentId 可以从工作台查询
        .build();
startActivity(intent);

指定客服分组分配

Intent intent = new LGIntentBuilder(this)
        .setScheduledGroup(groupId) // groupId 可以从工作台查询
        .build();
startActivity(intent);

设置预发送消息

Intent intent = new LGIntentBuilder(this)
        .setPreSendTextMessage("我是预发送文字消息")
        .setPreSendImageMessage(new File("预发送图片的路径"))
        .build();
startActivity(intent);

设置用户事件

LGClientEvent clientEvent = new LGClientEvent();
// 用户添加新产品
clientEvent.setEvent("add_product", "id_xxx"); // 事件字段需要先在后台创建
LGManager.getInstance().setClientEvent(clientEvent);

常见问题列表 #

• java.lang.NoClassDefFoundError: com.laigukf.core.xx
  没有依赖 okhttp3.5.0 或者 以上版本，检查依赖设置
• code == 400 track_id 错误
  如果需要绑定用户 id，请使用 setCustomizedId 接口；如果还是有问题，就换一个 id 绑定再试试
• 后台改了配置，SDK 不生效
  SDK 的配置不是立即生效，会至少间隔 15 分钟刷新一次，刷新后下次生效。如果想要立即看到配置改变的效果，可以卸载应用重新安装。

Proguard #

## ----------------------------------
##      OkHttp相关
## ----------------------------------
-keepattributes Signature
-keepattributes *Annotation*
-keep class com.squareup.okhttp3.** { *; }
-keep interface com.squareup.okhttp3.** { *; }
-dontwarn com.squareup.okhttp3.**
## ----------------------------------
##      Okio相关
## ----------------------------------
-keep class sun.misc.Unsafe { *; }
-dontwarn java.nio.file.*
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement
-dontwarn okio.**
## ----------------------------------
##      UIL相关
## ----------------------------------
-keep class com.nostra13.universalimageloader.** { *; }
-keepclassmembers class com.nostra13.universalimageloader.** {*;}
-dontwarn com.nostra13.universalimageloader.**
## ----------------------------------
##      Glide相关
## ----------------------------------
-keep class com.bumptech.glide.Glide { *; }
-keep public class * implements com.bumptech.glide.module.GlideModule
-keep public enum com.bumptech.glide.load.resource.bitmap.ImageHeaderParser$** {
  **[] $VALUES;
  public *;
}
-dontwarn com.bumptech.glide.**
-keep public class * implements com.bumptech.glide.module.GlideModule
-keep public class * extends com.bumptech.glide.module.AppGlideModule
-keep public enum com.bumptech.glide.load.ImageHeaderParser$** {
  **[] $VALUES;
  public *;
}
-dontwarn com.bumptech.glide.load.resource.bitmap.VideoDecoder
## ----------------------------------
##      Picasso相关
## ----------------------------------
-keep class com.squareup.picasso.Picasso { *; }
-dontwarn com.squareup.okhttp.**
-dontwarn com.squareup.picasso.**

API 接口介绍 #

获取 LGManager 实例后，

LGManager lgManager = LGManager.getInstacne(context);

就可以调用下面的接口：

设置当前 Client 上线 #

初始化 SDK 成功后，会默认生成一个顾客，如果没有更改过顾客 id，将以默认生成的顾客上线。

/**
* 设置当前 Client 上线
*
* @param onlineCallback 回调
*/
setCurrentClientOnline(final OnClientOnlineCallback onlineCallback)

绑定自定义 id 并设置上线 #

调用此接口后，当前可用的顾客即为该自定义 id 对应的顾客 id。

/**
* 绑定自定义 id，并设置上线
*
* @param customizedId   自定义 id
* @param onlineCallback 回调接口
*/
setClientOnlineWithCustomizedId(String customizedId, final OnClientOnlineCallback onlineCallback)

LGConversationActivity.class 内部调用了此接口，所以可以直接通过 LGIntentBuilder 来构造 intent。

Example:

// 假设 developer@dev.com 是开发者的用户 id
Intent intent = new LGIntentBuilder(this)
        .setCustomizedId("developer@dev.com") // 相同的 id 会被识别为同一个顾客
        .build();
startActivity(intent);

指定客服或者分组 #

来鼓默认会按照管理员设置的分配方式智能分配客服，但如果需要让来自 App 的顾客指定分配给某个客服或者某组客服。

/**
 * 指定客服或者分组，默认分配全企业
 *
 * @param agentId      指定客服的 id，不指定传 null
 * @param groupId      指定分组的 id，不指定传 null
 * @param scheduleRule 分配规则 LGScheduleRule.java
 */
setScheduledAgentOrGroupWithId(String agentId, String groupId, LGScheduleRule scheduleRule)

分配规则：

MQScheduleRule.REDIRECT_NONE // 指定分配客服失败，则进入留言
MQScheduleRule.REDIRECT_GROUP // 分配给组内的人，分配失败，则进入留言
MQScheduleRule.REDIRECT_ENTERPRISE // 分配给企业随机一个人，分配失败，则进入留言 （默认）

LGConversationActivity.class 内部调用了此接口，所以可以直接通过 LGIntentBuilder 来构造 intent。

Example:

Intent intent = new LGIntentBuilder(this)
        .setScheduledAgent(agentId) // agentId 可以从工作台查询
        .setScheduledGroup(groupId) // groupId 可以从工作台查询
        .setScheduleRule(LGScheduleRule.REDIRECT_ENTERPRISE) // 默认
        .build();
startActivity(intent);

注意：

• 该选项需要在用户上线前设置。

设置顾客离线 #

设置顾客离线后，将停止监听客服发送的消息，开发者不会再监听到即时消息广播。

如果设置了顾客离线，并且在来鼓工作台配置了推送服务器，则客服发送的消息将会发送给开发者的服务端。

建议：如果退出界面后需要监听客服消息，不设置顾客离线，这样开发者仍能监听到收到消息的广播，以便提醒顾客有新消息。

/**
* 设置顾客离线
* 需要初始化成功后才能调用
* 如果设置了顾客离线，则客服发送的消息将会发送给开发者的推送服务器
*/
setClientOffline()

发送文字消息 / 图片消息 / 语音消息 #

/**
 * 发送文字消息
 *
 * @param content               消息内容
 * @param onMessageSendCallback 消息状态回调
*/
sendLGTextMessage(String content, final OnMessageSendCallback onMessageSendCallback)
/**
 * 发送图片消息
 *
 * @param localPath             图片的本地路径
 * @param onMessageSendCallback 消息状态回调
 */
sendLGPhotoMessage(String localPath, final OnMessageSendCallback onMessageSendCallback)
/**
 * 发送语音消息
 *
 * @param localPath             语音的本地路径
 * @param onMessageSendCallback 消息状态回调
 */
sendLGVoiceMessage(String localPath, final OnMessageSendCallback onMessageSendCallback)

从服务器获取历史消息 #

/**
 * 从服务器获取历史消息
 *
 * @param lastMessageCreateOn  获取该日期之前的消息
 * @param length               获取的消息长度
 * @param onGetMessageListCallback 回调
 */
getLGMessageFromService(final long lastMessageCreateOn, final int length, final OnGetMessageListCallback onGetMessageListCallback)

从本地获取历史消息 #

/**
 * 从服务器获取历史消息
 *
 * @param lastMessageCreateOn  获取该日期之前的消息
 * @param length               获取的消息长度
 * @param onGetMessageListCallback 回调
 */
getLGMessageFromDatabase(final long lastMessageCreateOn, final int length, final OnGetMessageListCallback onGetMessageListCallback)

设置用户的设备唯一标识 #

/**
 * 设置用户的设备唯一标识
 *
 * @param token 唯一标识
 */
registerDeviceToken(String token, OkHttpUtils.OnRegisterDeviceTokenCallback onRegisterDeviceTokenCallback)

App 进入后台后，来鼓推送给开发者服务端的消息数据格式中，会有 deviceToken 的字段。

来鼓推送消息给开发者服务端的数据格式，可参考 推送消息数据结构。

开发者自定义当前顾客的信息 #

/**
 * 开发者自定义当前顾客的信息，用于展示给客服
 *
 * @param clientInfo           顾客信息
 * @param onClientInfoCallback 回调
 */
setClientInfo(Map<String, String> clientInfo, OnClientInfoCallback onClientInfoCallback)

为了让客服能更准确帮助用户，开发者可上传不同用户的属性信息。示例如下：

Map<String, String> info = new HashMap<>();
info.put("name", "富坚义博");
info.put("avatar", "your_avatar_url");
info.put("gender", "男");
info.put("tel", "111111");
info.put("技能1", "休刊");
info.put("技能2", "外出取材");
info.put("技能3", "打麻将");
LGManager.getInstance(context).setClientInfo(info, new OnClientInfoCallback());

LGConversationActivity.class 内部调用了此接口，所以可以直接通过 LGIntentBuilder 来构造 intent。

HashMap<String, String> clientInfo = new HashMap<>();
clientInfo.put("name", "富坚义博");
clientInfo.put("avatar", "your_avatar_url");
clientInfo.put("gender", "男");
clientInfo.put("tel", "1300000000");
clientInfo.put("技能1", "休刊");
Intent intent = new LGIntentBuilder(this)
        .setClientInfo(clientInfo)
        .build();
startActivity(intent);

以下字段是来鼓定义好的，开发者可通过上方提到的接口，直接对下方的字段进行设置：

获取当前正在接待的客服信息 #

/**
 * 获取当前正在接待的客服信息
 *
 * @return 如果存在，返回当前客服信息；不存在，返回 null
 */
getCurrentAgent()

获取当前顾客的 id #

/**
 * 获取当前顾客的顾客 id，开发者可保存该顾客id，下次使用 setClientOnlineWithLGClientId 接口来让该顾客登陆美洽客服系统
 *
 * @return 当前顾客 id
 */
getCurrentClientId()

获取一个新的顾客 #

/**
 * 获取一个新的顾客
 *
 * @param onGetLGClientIdCallBack 回调
 */
createLGClient(OnGetLGClientIdCallBackOn onGetLGClientIdCallBack)

如果开发者想初始化一个新的顾客，可调用此接口。

该顾客没有任何历史记录及用户信息。

结束当前对话 #

/**
 * 结束当前对话
 *
 * @param onEndConversationCallback 回调
 */
endCurrentConversation(OnEndConversationCallback onEndConversationCallback)

给客服发送「正在输入」 #

/**
 * 将用户正在输入的内容，提供给客服查看。该接口没有调用限制，但每1秒内只会向服务器发送一次数据
 *
 * @param content 正在输入的内容
 */
sendClientInputtingWithContent(String content)

切换当前顾客 #

/**
 * 切换当前顾客
 *
 * @param clientIdOrCustomizedId clientId 或者 customized
 * @param simpleCallback         回调
 */
LGManager.getInstance(context).setCurrentClient(String clientIdOrCustomizedId, SimpleCallback simpleCallback);

获取未读消息 #

退出界面后收到的消息，都将算作未读消息。

/**
 * 获取当前 Client 的未读消息
 *
 * @param onGetMessageListCallback 回调
 */
LGManager.getInstance(context).getUnreadMessages(new OnGetMessageListCallback());

/**
 * 获取指定 ClientId 或者 customized 顾客的未读消息
 *
 * @param clientIdOrCustomizedId   clientId 或者 customized
 * @param onGetMessageListCallback 回调
 */
LGManager.getInstance(context).getUnreadMessages(String clientIdOrCustomizedId, new OnGetMessageListCallback());

接收即时消息 #

在未开启 离线消息推送 的情况下，开发者可以通过注册一个 BroadcastReceiver ，监听广播

注意：必须通过 LocalBroadcastManager 注册 和 取消注册 BroadcastReceiver。

Example:

// 注册
LocalBroadcastManager.getInstance(this).registerReceiver(messageReceiver, intentFilter);
// 取消注册
LocalBroadcastManager.getInstance(this).unregisterReceiver(messageReceiver);

BroadcastReceiver：

public class MessageReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
         // 获取 ACTION
         final String action = intent.getAction();
         // 接收新消息
         if (LGMessageManager.ACTION_NEW_MESSAGE_RECEIVED.equals(action)) {
             // 从 intent 获取消息 id
             String msgId = intent.getStringExtra("msgId");
             // 从 MCMessageManager 获取消息对象
             LGMessageManager messageManager = LGMessageManager.getInstance(context);
             LGMessage message = messageManager.getLGMessage(msgId);
             // do something
         }
         // 客服正在输入
         else if (LGMessageManager.ACTION_AGENT_INPUTTING.equals(action)) {
             // do something
         }
         // 客服转接
         else if (LGMessageManager.ACTION_AGENT_CHANGE_EVENT.equals(action)) {
             // 获取转接后的客服
             LGAgent lgAgent = messageManager.getCurrentAgent();
             // do something
         }
     }
 }

获取 SDK 版本号 #

/**
 * 获取 SDK 版本号
 */
getLaiguSDKVersion()

离线消息推送 #

当前仅支持一种推送方案，即来鼓服务端发送消息至开发者的服务端，开发者再推送消息到 App。

设置接收推送的服务器地址 #

推送消息将会发送至开发者的服务器。

设置服务器地址，请使用来鼓管理员帐号，在「设置」 -> 「SDK」中设置。

设置用户的设备唯一标识 #

/**
 * 设置用户的设备唯一标识
 *
 * @param token 唯一标识
 */
registerDeviceToken(String token, OkHttpUtils.OnRegisterDeviceTokenCallback onRegisterDeviceTokenCallback)

关闭来鼓服务，来鼓推送给开发者服务端的消息数据格式中，会有 deviceToken 的字段。

关闭来鼓服务 #

关闭服务后，将停止监听消息，此时来鼓服务端将会推送消息给开发者提供的消息推送服务端，如下代码：

LGManager.getInstance(context).closeLaiguService();

来鼓建议：在 App 后台以后，关闭来鼓服务。App 进入前台，如果需要监听客服消息，再开启来鼓服务。

开启来鼓服务 #

开启服务后，将重新监听消息，此时来鼓服务端将不会推送消息给开发者提供的消息推送服务端，如下代码：

LGManager.getInstance(context).openLaiguService();

来鼓建议：在 App 后台以后，关闭来鼓服务。App 进入前台，如果需要监听客服消息，再开启来鼓服务。

推送消息数据结构 #

当有消息需要推送时，美洽服务器会向开发者设置的服务器地址发送推送消息，方法类型为 POST，数据格式为 JSON 。

发送的请求格式介绍：

request.header.authorization 为数据签名。

request.body 为消息数据，数据结构为：

开发者可以根据请求中的签名，对推送消息进行数据验证，美洽提供了 Java、Python、Ruby、JavaScript、PHP 5种语言的计算签名的代码，具体请移步 来鼓 SDK 3.0 推送的数据结构签名算法。

自定义UI #

• 配置标题文本对其方式

• 通过在自己工程中覆盖相应资源ID的方式配置自定义 UI「这里只列出常用自定义属性，如需特殊定制，请查看来鼓 SDK 源码里相应的资源 ID 并在自己工程中覆盖」

• 以下属性可通过 Java 代码的方式配置「不建议使用这种方式」

自定义业务 #