移动 SDK

移动 SDK 相当于面向您自己应用的网页小组件：您的客户可以在应用内获得支持，享有完整的对话历史和推送通知，您的客服则在同一个收件箱中看到这些对话。它们不是给您团队使用的客服应用；客服应用是另一条产品线。

平台

平台	语言和运行时	分发方式	状态
iOS	Swift 5.9+、iOS 15+	Swift Package Manager、CocoaPods	开发中
Android	Kotlin 1.9+、Android 8.0（API 26）+	Maven Central	开发中
React Native	封装原生 SDK	npm	计划中（测试版）
Flutter	封装原生 SDK	pub.dev	计划中（测试版）

原生 SDK 是权威版本；封装层在其之后发布。手表或电视应用以及桌面 SDK 不在范围内；桌面端请使用网页小组件。

SDK 包含的内容

文本消息、附件、语音消息、图片和视频、匿名和已识别的会话、主题设置、自定义头像和品牌、40 种语言、AI 礼宾、对话历史、未读徽标、推送通知、深层链接、通过手机拨号程序点击拨号、带后台同步的离线队列、聊天的生物识别解锁、VoiceOver 和 TalkBack 支持、深色模式。每个平台的目标编译大小为 5 MB 或更小。

应用内 WebRTC 通话和客户端屏幕共享将在后续版本中推出。协同浏览仅限网页：移动操作系统不允许第三方 SDK 观察或控制屏幕。

SDK 接口

在应用生命周期的早期初始化一次：

// iOS
let config = RolChatConfig(
  siteId: "site_abc123",
  apiKey: "pk_live_…",      // public key - safe to ship in the app
  region: .eu,              // eu / us
  theme: RolChatTheme(primaryColor: .blue)
)
RolChat.shared.initialize(config: config)

// Android
val config = RolChatConfig.Builder()
  .siteId("site_abc123")
  .apiKey("pk_live_…")
  .region(Region.EU)
  .theme(RolChatTheme(primaryColor = Color.Blue))
  .build()
RolChat.initialize(context, config)

在用户登录后识别用户，并在用户退出时退出：

RolChat.shared.identify(userId: "user_12345", email: "alice@example.com", name: "Alice",
                        metadata: ["tier": "gold"])
RolChat.shared.logout()   // on host-app sign-out, or the next user sees this history

显示界面：

RolChat.shared.openChat()                      // modal
RolChat.shared.openChat(conversationId: id)    // a specific conversation
RolChat.shared.openChatInline(view)            // inside your own layout
RolChat.shared.close()

回调：rolChatDidOpen、rolChatDidClose、rolChatDidReceiveMessage(_:)、rolChatDidFailToSend(_:)。公开 API 在 iOS 上可在主线程安全调用，在 Android 上可在后台线程安全调用；应用进入后台时连接会断开，回到前台时恢复。

会话和身份

匿名：存储在钥匙串或加密偏好设置中的设备会话 ID 在应用更新后仍然保留，并与设备而不是用户绑定。连续 90 天不活动后会被清除。
已识别：调用 identify 后，会话会被提升，并在明确无歧义时与同一设备上的匿名历史合并。跨渠道的身份解析遵循身份图谱规则和同意设置。
可信识别：您的后端使用用户的声明为令牌签名；SDK 传递该令牌，RolChat 在提升会话之前验证签名。未签名的 identify 也能工作，但可信度较低。

应用中的公开 API 密钥在设计上是安全的：它限定于站点范围并受速率限制。

推送通知

平台	传输方式	您需要提供
iOS	APNs	在 RolChat 仪表板中配置的 APNs 认证密钥
Android	FCM	FCM 服务账号 JSON

RolChat.shared.setPushToken(deviceToken, type: .apns)
if RolChat.shared.handleNotification(userInfo) { return }   // consumed: a chat message

通知文本会在服务器端根据用户的区域设置进行本地化。富通知支持头像、从通知直接回复和标记为已读。SDK 绝不会自行请求推送权限；请在适合您入门流程的时机调用 requestPushPermission()。退出可以通过 setPushEnabled(false) 或系统设置完成；两者都会被记录。

版本控制和支持

严格遵循语义化版本控制。同时支持两个主版本，主版本发布后有一年的迁移期。次要版本每月发布；安全修复立即发布；主版本提前三个月公布。已弃用或不受支持的 SDK 会在启动时记录警告，仪表板会在“集成”下显示。

隐私

除您启用的内容外不做任何跟踪，同意界面使用平台的原生模式，GDPR、CCPA 和 LGPD 数据主体请求与其他渠道一样涵盖 SDK 会话。附件在设备上压缩，上传到签名 URL，并在客服看到之前进行病毒扫描。