访客端 App 接入

将访客聊天能力嵌入 Android、iOS 或 Flutter App。SDK 统一处理 WebView 加载、原生权限、下载回传、消息事件和页面生命周期。

选择接入方式

方式	适用场景	宿主需要负责
访客SDK接入文档	新接入的移动端项目，需要现成的容器和平台回调	SDK 配置、权限声明、下载处理和 App 导航
APP 嵌入访客端 WebView	已经自建 WebView，并且需要沿用现有 AppBridge 协议	WebView 配置、桥接层注入、消息校验和原生处理

新项目建议优先使用 SDK；已有 WebView 和 AppBridge 协议的项目，请按第二篇文档接入，避免同时维护两套桥接逻辑。

支持平台

平台	最低要求	依赖
Android	minSdk 23	Maven Central：io.github.twt-chat:visitor-sdk:0.0.1
iOS	iOS 15+	Swift Package Manager：TwtVisitorSDK
Flutter	Flutter ≥ 3.44，Dart ^3.12.2	Git：visitor_flutter

推荐接入流程

1. 按平台添加依赖，并声明 App 实际使用的权限。
2. 打开 HTTPS 访客页，通过 SDK 的 query 传入业务参数。
3. 监听下载、消息、权限和页面生命周期回调。
4. 使用原始 requestId 回传下载成功或失败状态。
5. 切换账号前关闭访客页，确认会话释放后再清理站点数据。

安全与生命周期要点

• 仅使用 HTTPS，不要把密码、Cookie、AppSecret 或长期 token 放进访客 URL。
• 下载地址、回调数据和页面事件都应视为外部输入，交给原生 API 前先校验。
• 只有在用户触发对应操作时，再申请麦克风或摄像头权限。
• 使用 requestId、messageId 去重；页面销毁时，将未完成下载标记为失败。
• 弱网、后台、锁屏、文件选择、下载和 WebSocket 重连请在真机验证。

完整的平台代码和配置请查看访客SDK接入文档。