合从文档中心

Appearance

装进 iOS ​

用 Swift Package Manager 添加依赖，写两行代码，APP 里就有了客服入口。

开始之前 ​

  • 一个渠道 ID，工作台 App 渠道的 SDK 接入 页把它嵌在初始化代码里，也可以在 开发者 页的 接入参数 卡单独复制，见创建 App 渠道
  • APP 的部署目标不低于 iOS 13
  • Xcode 能访问 GitHub（SDK 通过 Swift Package Manager 分发）

动手之前可以先跑一遍示范 App：扫码装上，填进你的渠道 ID 就连到你的工作台。先确认渠道和账号这一侧是通的，之后自己集成再出问题，范围就缩小到你的工程配置。

操作步骤 ​

1. 添加依赖 ​

在 Xcode 里选择 File > Add Package Dependencies，在搜索框里填仓库地址：

https://github.com/sandywk/hecong-ios-sdk

依赖规则选 Up to Next Major Version，版本填 0.6.4，把 HecongChatSDK 添加到你的 APP target。

用 Package.swift 管理依赖的工程写成：

swift
.package(url: "https://github.com/sandywk/hecong-ios-sdk", from: "0.6.4")

已发布的版本都列在仓库的 tags 页面。

国内网络拉取可能较慢

Swift Package Manager 从 GitHub 拉取源码，国内网络下首次解析依赖可能需要等待较久。Xcode 会持续显示解析进度，这是网络问题，不是集成出错。

Swift Package Manager 只在编译期工作，它不会抬高你的 APP 的运行时最低版本要求。

2. 登记渠道 ID ​

在 APP 启动流程里调一次 configure：

swift
import HecongChatSDK

HecongChat.shared.configure(HecongChatConfig(channelId: "你的渠道ID"))

这一步只登记参数，不产生任何网络请求，也不收集任何信息。

放在用户同意隐私政策之后

虽然这一步本身零联网，仍建议放在用户同意隐私政策之后再调用。把所有第三方 SDK 的初始化统一放在同意之后，是应对隐私合规审核最省事的做法。

想让客户第一次点开客服更快，configure 之后可以再调一次 HecongChat.shared.prewarm()，SDK 会提前把整个聊天页准备好。这一步会联网，必须放在用户同意隐私政策之后；不调也能正常用，只是第一次打开要多等一下。

3. 打开客服 ​

在「联系客服」的点击事件里：

swift
HecongChat.shared.push(config: HecongChatConfig(channelId: "你的渠道ID"))

SDK 自己找到当前的导航栏，把客服页推进去，标题填成「在线客服」（你已经设过标题的话不覆盖），底部 Tab 栏自动隐藏。不用传任何页面或导航控制器，UIKit 和 SwiftUI 工程写法一样。 标题可以改成你自己的，配置项见聊天页的四种形态。

键盘避让、安全区适配、前后台切换，SDK 内部处理，你不需要额外做什么。

打开客服还有另外三种方式：半屏弹层、嵌进自己的页面、整屏沉浸。调用方法各不相同，效果对比见聊天页的四种形态 —— 四档共用同一套配置，换档不影响你已经接好的东西。

4. 填好权限用途说明 ​

客户要发语音和拍照，APP 需要麦克风和相机权限。在 Info.plist 里补两条用途说明：

键填什么
NSMicrophoneUsageDescription说明在客服会话中录制语音消息需要使用麦克风
NSCameraUsageDescription说明在客服会话中拍摄照片或视频发给客服需要使用相机

苹果会审核这两句话的内容。写清楚是哪个功能、用来做什么，只写「需要相机」这类空泛描述会被拒。相册选择不需要单独声明。

语音消息对系统版本有额外要求，写应用市场文案前先看文件上传限制。

隐私清单不用你操心

苹果要求第三方 SDK 随包提供隐私清单。合从的 SDK 已经内置，你不需要为它补任何声明。提交时如果收到 ITMS-91053、ITMS-91055 这类隐私清单告警，来源是别的依赖，排查方向不在合从这边。

验证接入成功 ​

把 APP 装到手机或模拟器上，点开客服，你应该看到一个完整的对话界面。发一条消息，在客服工作台的对话列表里能看到它。

iOS 上的客服对话界面

App 渠道的会话不能在浏览器里验证，原因见 APP 接入概述。

用 Objective-C 写 ​

SDK 的公共接口都可以从 Objective-C 调用。导入方式要用 @import，不能写成 #import <HecongChatSDK/HecongChatSDK-Swift.h> —— 那是框架形态的写法，通过 Swift Package Manager 引入时那个头文件路径不存在，照写编译不过。

需要工程开启 Clang 模块（CLANG_ENABLE_MODULES = YES），Xcode 新建的工程默认就是开的。

objc
// SPM 引入的 Swift 包在 Objective-C 里用模块导入，不是头文件导入
@import HecongChatSDK;

// APP 启动时
HecongChatConfig *config = [[HecongChatConfig alloc] initWithChannelId:@"你的渠道ID"];
[[HecongChat shared] configure:config];

// 打开客服
[[HecongChat shared] pushWithConfig:config];

常见问题 ​

Xcode 解析依赖一直转圈 ​

症状：添加 Package 之后长时间停在 Resolving Packages。

成因：从 GitHub 拉取源码受网络影响。

解决：等待或换用更稳定的网络环境。已经解析失败的，在 File > Packages > Reset Package Caches 之后重试。

点开客服是一片空白 ​

症状：客服页面推进来了，但里面什么都没有。

成因：多数是网络问题，设备连不上合从的服务。

解决：确认设备网络正常。断网时 SDK 会显示一张带重试的提示页，看到那张页面说明 SDK 本身正常。

客户在 APP 里退出登录后，下一个人看到了上一个人的记录 ​

症状：同一台设备上换个账号登录，客服对话里还是上一位的历史消息。

成因：退出登录时没有通知 SDK 解绑身份。

解决：在退出登录的流程里调 HecongChat.shared.resetUser()，见传客户资料与退出登录。

上线前对照一遍 ​

装通了只是第一步，下面这些漏掉的症状都比较隐蔽，上线前逐条确认：

  • [ ] 退出登录时调了 resetUser()。不调的话，下一个在同一台设备登录的人会看到上一位的聊天记录（做法）
  • [ ] 多进程 APP 设了 WebView 数据目录后缀，不设会直接崩溃（做法）
  • [ ] 真机切到后台，工作台里这位客户变成离线。不变说明前后台事件没接，离线推送一条都不会发（做法）
  • [ ] 配了离线消息通知的话，服务端真收到过一次回调（怎么自测）
  • [ ] 要做未读红点的话，调了 startUnreadTracking()（做法）
  • [ ] 提交应用市场前，按隐私合规与信息公示把 SDK 公示信息填进你的隐私政策 —— 漏了会被打回
  • [ ] Info.plist 里两条权限用途说明都写清楚了具体功能与用途（做法）

下一步 ​