Appearance
接口速查
Android 与 iOS 对照列出。使用说明见各功能页。
依赖
| 端 | 怎么装 |
|---|---|
| Android | implementation("com.aihecong:hecong-chat-sdk:0.6.4")，Maven Central |
| iOS | Swift Package Manager，仓库地址 https://github.com/sandywk/hecong-ios-sdk |
最低版本：iOS 13、Android 5.0（API 21）。
配置项
创建配置对象时只有渠道 ID 必填，其余都有默认值。
| 配置项 | 默认值 | 说明 |
|---|---|---|
channelId | 无，必填 | 工作台 App 渠道详情页复制 |
colorScheme | host | 深浅色，四档取值见深色模式 |
routing | 空 | 指定接待的技能组，见指定技能组接待 |
deviceId | 空 | 你自己的设备标识，别当推送对照依据（为什么） |
anonymousIdScope | 空 | 同一个 APP 接多个渠道时，用它把各渠道的访客标识分开 |
errorReportingEnabled | true | SDK 自身运行错误的上报开关，见下方错误上报 |
unreadPollIntervalSecondsunreadPollInterval | 60 | 未读查询间隔（秒），最低 30。上为 Android、下为 iOS |
permissionRationaleText | 内置话术 | 仅 Android。权限说明文案，分 microphone / camera |
extraQuery["lang"] | 空 | 客服页面语言，不传用系统语言（详见） |
title | 「在线客服」 | 标题栏文字，跟随语言设置，见聊天页的四种形态 |
titleFollowsAgent | false | 客服接待后把标题换成客服昵称 |
headerBackgroundColor | 跟随深浅色 | 标题栏背景色 |
titleColor | 跟随深浅色 | 标题文字颜色 |
backIconRes（Android）backImage（iOS） | 系统返回箭头 | 换成你自己的返回图标 |
sheetHeightRatio | 0.82 | 弹层档卡片占屏幕高度的比例，取值 0.3 ~ 1.0 |
modernInsets（仅 Android） | true | 键盘与系统栏的新式适配，关掉退回传统方式 |
方法
不打开客服页面也能调，SDK 会记住，页面打开时自动生效。
Android
| 做什么 | 方法 |
|---|---|
| 登记配置 | HecongChat.configure(context, config) |
| 打开客服（标准档） | HecongChatActivity.start(context, config) |
| 打开客服（弹层档） | HecongChatActivity.startSheet(context, config, useChannelHeader) |
| 打开客服（沉浸档） | HecongChatActivity.startImmersive(context, config) |
| 嵌进自己的页面 | HecongChatFragment.newInstance(config) |
| 绑定会员 | HecongChat.identify(userId, profile, data) |
| 退出登录 | HecongChat.resetUser() |
| 开启未读跟踪 | HecongChat.startUnreadTracking(listener) |
| 停止未读跟踪 | HecongChat.stopUnreadTracking() |
| 指定技能组 | HecongChat.setRouting(skillGroup, fallback, fallbackGroup) |
| 加输入区按钮 | HecongChat.registerAction(id, label, slot, icon) |
| 撤掉按钮 | HecongChat.unregisterAction(id) |
| 带入咨询内容 | HecongChat.setPresend(text, card) / HecongChat.clearPresend() |
| 供给选择器数据 | HecongChat.setPickerData(picker, items) |
| 打开选择器 | HecongChat.openPicker(picker) |
iOS（都在 HecongChat.shared 上）
| 做什么 | 方法 |
|---|---|
| 登记配置 | configure(config) |
| 打开客服（标准档） | push(config:) |
| 打开客服（弹层档） | presentSheet(config:useChannelHeader:) |
| 打开客服（沉浸档） | presentImmersive(config:) |
| 嵌进自己的页面 | HecongChatViewController(config:) |
| 绑定会员 | identify(userId:profile:data:) |
| 退出登录 | resetUser() |
| 开启未读跟踪 | startUnreadTracking(listener:) |
| 停止未读跟踪 | stopUnreadTracking() |
| 指定技能组 | setRouting(_:) |
| 加输入区按钮 | registerAction(id:label:icon:slot:) |
| 撤掉按钮 | unregisterAction(_:) |
| 带入咨询内容 | setPresend(text:card:) / clearPresend() |
| 供给选择器数据 | setPickerData(_:items:) |
| 打开选择器 | openPicker(_:) |
registerAction 两端的参数顺序不同：Android 是 slot 在前、icon 可省，iOS 是 icon 在前、两个都要传。
profile 可传 name、avatar、phone、email 四个字段，data 传你自己的业务字段，约束见传客户资料。
回调
Android 实现 HecongChatListener，iOS 实现 HecongChatDelegate，全部可选。
| 什么时候来 | Android | iOS |
|---|---|---|
| 客服页面就绪 | onReady() | hecongChatReady() |
| 未读数变化 | onUnreadChanged(count) | hecongChatUnreadDidChange(_:) |
| 会员绑定成功 | onIdentified(userId) | hecongChatDidIdentify(_:) |
| 自定义字段被忽略 | onCustomFieldsIgnored(keys) | hecongChatDidIgnoreCustomFields(_:) |
| 退出登录完成 | onUserReset() | hecongChatDidResetUser() |
| 访客标识变化 | onAnonymousIdChanged(id) | hecongChatDidChangeAnonymousId(_:) |
| 输入区按钮被点 | onActionClick(id) | hecongChat(didClickAction:) |
| 消息里的外链被点 | onOpenUrl(url) | hecongChat(handleOpenUrl:) |
| 附件要下载 | onDownload(url, filename) | hecongChat(handleDownload:filename:) |
| 客户点了关闭 | onClose() | hecongChatDidRequestClose() |
| 页面加载失败 | onLoadFailed(reason) | hecongChatDidFailToLoad(_:) |
| 标题栏身份变化 | onHeaderIdentityChanged | hecongChatHeaderIdentityDidChange(_:) |
| 要弹权限说明 | onShowPermissionRationale | 无，iOS 走系统弹窗 |
返回布尔值的四个回调（外链、下载、关闭、权限说明），返回 true 表示你自己处理了，SDK 不再做默认动作。外链回调同时承接电话、邮箱、短信，接管前要按协议判断，见聊天页里的外链与拨号。
标题栏身份
自己画标题栏时用得上。这份数据只有客服页面内部有，而且会变：会话开始前显示渠道身份，客服接起后变成客服的昵称头像，转接后再变一次。
| 字段 | 说明 |
|---|---|
nickname | 昵称 |
avatar | 头像地址 |
signature | 签名 |
pending | 为真时数据还没确定，你也应该显示占位，否则会先空一下再跳出名字 |
会话事件
通用回调 onEvent(name, payload) / hecongChat(didReceiveEvent:payload:) 收全部事件。事件名与网页接入一致。
| 事件名 | 具名回调（Android） | 具名回调（iOS） |
|---|---|---|
message:incoming | onIncomingMessage | hecongChat(didReceiveIncomingMessage:) |
message | onMessage | hecongChat(didReceiveMessage:) |
conversation:start | onConversationStart | hecongChatConversationDidStart(_:) |
conversation:end | onConversationEnd | hecongChatConversationDidEnd(_:) |
network:online / offline | onNetworkChanged | hecongChatNetworkDidChange(_:) |
通用回调和具名回调二选一，两边都接会处理两次。取舍见监听会话事件。
自己嵌容器时要转发的
用 HecongChatView 把对话嵌进自己布局时，Android 侧需要转发 onActivityResult、onRequestPermissionsResult、onHostStart、onHostStop，并在销毁时调 destroy()。用了自己的返回按钮还要转发 handleBackPressed()。详见把聊天嵌进自己的页面。
错误上报
SDK 默认会上报自身的运行错误，用于发现加载失败、权限异常这类问题。上报内容不包含聊天内容，也不包含客户资料。
SDK 不安装任何全局崩溃捕获，不会影响你自己的崩溃监控工具。
要关闭，把 errorReportingEnabled 设为 false。