TWT Visitor SDK
在 App 内打开访客聊天页面。宿主传入 HTTPS 地址后,SDK 使用系统 WebView / WKWebView / ArkWeb 加载,并处理导航、权限、下载回传与站点数据清理。
不使用 SDK、App 自建 WebView 打开访客页,见 访客端 WebView 自行接入。
当前版本:0.0.4
| 平台 | 要求 | 集成 |
|---|---|---|
| Android | minSdk 23 | Maven Central:io.github.twt-chat:visitor-sdk:0.0.4 |
| iOS | iOS 15+ | SPM:https://github.com/TWT-Chat/twt-visitor-ios.git(tag 0.0.4,产品 TwtVisitorSDK) |
| Flutter | Flutter ≥ 3.44,Dart ^3.12.0 | Git:https://github.com/TWT-Chat/visitor_flutter.git(ref 0.0.4) |
| HarmonyOS | HarmonyOS 6.1(API 23)+ | ohpm 中心仓:twt_visitor_sdk@0.0.4;也可本地依赖 SDK 源码仓库中的 visitor_oh/twt_visitor_sdk |
集成
Android
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
}
}
dependencies {
implementation("io.github.twt-chat:visitor-sdk:0.0.4")
}
SDK 已合并 INTERNET、RECORD_AUDIO、CAMERA(required=false)。Android 9 及以下若下载到公共 Downloads,请自行添加 WRITE_EXTERNAL_STORAGE。
iOS
Xcode → File → Add Package Dependencies,填入:
https://github.com/TWT-Chat/twt-visitor-ios.git
Dependency Rule 选择 Exact Version 0.0.4,产品勾选 TwtVisitorSDK。Deployment Target ≥ iOS 15。
在 Info.plist 中声明:
<key>NSMicrophoneUsageDescription</key>
<string>用于发送语音消息</string>
<key>NSCameraUsageDescription</key>
<string>用于拍摄并发送照片或视频</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>用于保存会话图片</string>
<key>UIFileSharingEnabled</key>
<true/>
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>
请保持 App Transport Security 默认设置。公开 API 须在主线程调用。
Flutter
dependencies:
visitor_flutter:
git:
url: https://github.com/TWT-Chat/visitor_flutter.git
ref: 0.0.4
flutter pub get
Android 端需配置 mavenCentral()(见上方 Android 集成)。若使用 RepositoriesMode.PREFER_SETTINGS,还须保留 Flutter Engine 仓库 https://storage.googleapis.com/download.flutter.io。iOS 端无需再添加 SPM,按 iOS 一节配置 Info.plist 即可。
HarmonyOS
最低系统 HarmonyOS 6.1(API 23)。在入口模块的 oh-package.json5 中从 ohpm 中心仓安装:
{
"dependencies": {
"twt_visitor_sdk": "0.0.4"
}
}
中心仓上是 bytecode HAR,宿主工程的 build-profile.json5 必须保持 strictMode.useNormalizedOHMUrl = true(DevEco 模板默认值),关掉会在编译期报 00306046 Bytecode HAR [twt_visitor_sdk] not supported when useNormalizedOHMUrl is not true。
不走中心仓时:源码目录用 "twt_visitor_sdk": "file:../twt_visitor_sdk"(即 visitor_oh/twt_visitor_sdk),或直接 ohpm install ./libs/twt_visitor_sdk-0.0.4.har。许可为 Apache-2.0(Android / iOS 目前是 Proprietary)。
HAR 已声明 ohos.permission.INTERNET、ohos.permission.MICROPHONE、ohos.permission.CAMERA。用户授权权限不能只靠 HAR 生效,宿主 HAP 还必须在自己的 module.json5 里再声明 MICROPHONE / CAMERA(示例 visitor_oh/entry/src/main/module.json5 已演示)。
快速开始
接入方只需搞清三件事:
url(必填):控制台配置的 URL 地址,必须 HTTPS。- 配置项:SDK 认识的字段(
isApp/language/theme/directChatId/newMessageSoundMode)。都有默认值,可不传。 query:给访客页的业务参数。SDK 不解释 key,只负责 UTF-8 编码拼进 URL。匿名访客可以不传。
不要自己拼 ?a=1&b=2。不要把密码、Cookie、AppSecret 或长期 token 放进 URL。
最少打开(只传 url)时 SDK 拼出:
控制台配置的 URL 地址?lang=zh-cn&theme=system
lang=zh-cn、theme=system 由默认配置写入。App 内若要显示关闭按钮,再设 isApp = true。
Android
val handle = TwtVisitorSdk.start(
this,
VisitorConfig(url = "控制台配置的 URL 地址"),
)
start 会先校验配置,URL 为空或不是 HTTPS 时抛 IllegalArgumentException,宿主需要 try / catch。校验通过后打开 VisitorActivity 并返回 VisitorHandle。传入非 Activity Context 时会自动加上 FLAG_ACTIVITY_NEW_TASK。下载、新消息等回调见「回调与事件」。
要自己画标题栏就用 embed,拿到裸 WebView 放进自己的布局:
val visitorView = TwtVisitorSdk.embed(this, config, listener)
// 自己的工具栏(返回键 + 标题)在最上面,visitorView 放它下面
示例页是普通页面:顶部系统状态栏,下面是自绘的 56dp 工具栏(返回键 + 网页标题),再下面是 WebView。targetSdk 35+ 强制 edge-to-edge,宿主需要给根布局补 WindowInsetsCompat.Type.systemBars() 的 padding(示例里是 applySystemBarInsets()),否则工具栏会被状态栏压住。
宿主要把 onBackPressed(visitorView.handleBack(::finish))、onResume / onPause、onDestroy(visitorView.destroySession())、onActivityResult、onRequestPermissionsResult 转发给它。完整示例见 android/sample/.../EmbeddedVisitorActivity.kt。
iOS
打开独立页(整屏裸 WebView):
import TwtVisitorSDK
let config = VisitorConfiguration(
url: URL(string: "控制台配置的 URL 地址")!
)
let handle = try TwtVisitorSDK.present(from: self, configuration: config, delegate: self)
.fullScreen 呈现,没有系统返回手势,SDK 也不画任何容器 UI、不处理返回,也不转发页面里的 close。要退出只能靠宿主自绘的按钮调 handle.close()(或自己 dismiss)。dismiss 之后 handle 失效。
需要标题栏和返回键就自己包一层容器:
let controller = try TwtVisitorSDK.makeEmbeddedController(configuration: config, delegate: self)
let container = UINavigationController(rootViewController: controller)
// iOS 26 的导航栏是玻璃的,会采样 WebView 底色,给不透明 appearance 才稳。
let appearance = UINavigationBarAppearance()
appearance.configureWithOpaqueBackground()
container.navigationBar.standardAppearance = appearance
container.navigationBar.scrollEdgeAppearance = appearance
controller.navigationItem.leftBarButtonItem = UIBarButtonItem(
image: UIImage(systemName: "chevron.backward"),
primaryAction: UIAction { [weak container] _ in container?.dismiss(animated: true) }
)
present(container, animated: true)
网页标题通过 visitorTitleChanged(_:) 回填到 controller.navigationItem.title。
Flutter
宿主自建页面(推荐):Scaffold + 自己的 AppBar,WebView 只占内容区:
import 'package:visitor_flutter/visitor_flutter.dart';
final config = VisitorConfiguration(url: '控制台配置的 URL 地址');
Scaffold(
appBar: AppBar(title: Text(_webTitle ?? '在线客服')), // _webTitle 来自 titleChanged
body: VisitorView(configuration: config),
)
VisitorView 必须放在有确定尺寸的父布局中(如 Scaffold 的 body、Expanded、SizedBox)。
传入新的 configuration(URL、query、isApp、language、theme、directChatId)会重建平台视图并加载新地址;只改 newMessageSoundMode 不重载页面。运行中切主题用 VisitorFlutter.setTheme,不要改 configuration。
打开独立原生页:
final handle = await VisitorFlutter.present(configuration: config);
Android 上它是 SDK 的 Activity,系统返回键由 SDK 处理(页面优先,未消费才关)。iOS 上它是整屏裸 WebView,既没有系统返回手势,SDK 也不给关闭入口,建议改用上面的宿主自建页面,否则用户退不出去。
HarmonyOS
打开独立页(裸 WebView,无标题栏,系统返回由 SDK 处理):
import { common } from '@kit.AbilityKit';
import { TwtVisitorSDK, VisitorConfig, VisitorHandle } from 'twt_visitor_sdk';
const config = new VisitorConfig();
config.url = '控制台配置的 URL 地址';
config.isApp = true;
const handle: VisitorHandle | null = TwtVisitorSDK.start(
getContext(this) as common.UIAbilityContext,
config,
listener,
);
if (handle === null) {
// URL 或 query 非法,SDK 不会打开页面
}
与 Android 不同,URL 非法时 start 返回 null,不抛异常。
使用独立页时,在宿主入口 import 一次页面文件,确保命名路由已注册:
import 'twt_visitor_sdk/src/main/ets/pages/VisitorPage';
要自己画标题栏就用 embed + VisitorView:
const session = TwtVisitorSDK.embed(config, listener);
// 自己的标题栏(返回键 + 标题)在最上面,VisitorView 放它下面
VisitorView({ session: session })
SDK 不画任何 chrome;网页标题由 VisitorBridgeListener.onTitleChanged 回传。返回键和系统返回都调 session.handleBack(() => { ... }):SDK 先问页面(300ms),页面未消费且 WebView 无历史时才执行回调。完整示例见 visitor_oh/entry/src/main/ets/pages/EmbeddedPage.ets。
配置项
四端字段相同。SDK 会把部分配置写成 URL query,并覆盖 query 里的同名 key。
| 字段 | 默认 | 进 URL? | 说明 |
|---|---|---|---|
url | 空(必填) | 基址 | 控制台配置的 URL 地址,仅 HTTPS。HTTP、file、javascript、自定义 scheme、带 user:pass 的地址会被拒绝 |
query | 空 Map | 原样拼接 | 业务参数,见下一节。不要手拼 ?a=1 |
isApp | false | true 时写 is_app=1 | App 内打开,访客页显示关闭按钮。false 不写 is_app=0 |
language | zh-cn | 每次都写 lang | en / zh-cn / zh-tw / ja / ko / de / fr / pt / ru / es / vi / th / id / ms / tl |
theme | system | 每次都写 theme | light / dark / system。运行时 setTheme 只接受 light / dark |
directChatId | null | 有值时写 direct=1&chatid= | 直达会话,并去掉 chat_id |
newMessageSoundMode | web | 一般否 | web:页面播放;native:宿主在新消息回调中播放。走 JS 桥,不靠 URL(Flutter Android present() 会额外带 new_message_sound_mode) |
写入顺序:url 自带 query → config.query → is_app / lang / theme / direct+chatid。后者覆盖前者。
query 业务参数
query 是透明 Map,SDK 只编码拼接,不解释 key。匿名访客可以整份不传。is_app / lang / theme / direct / chatid 用配置项,不要再写进 query。
绑业务用户时:
query = mapOf(
"sbs" to "user-123",
"sbs_mm" to signature,
"ranstr" to randomStr,
"name" to "张三",
)
| 参数 | 必填? | 含义 |
|---|---|---|
sbs | 绑用户时必填 | 业务系统里的用户唯一 ID,访客页用它识别已登录客户 |
sbs_mm | 有 sbs 就要 | sbs 的签名 |
ranstr | 有签名就要 | 参与签名的随机串 |
name | 可选 | 访客姓名,进入客服工作台展示 |
nickname | 可选 | 访客昵称 |
email | 可选 | 访客邮箱 |
phone | 可选 | 访客手机号 |
customer_remark | 可选 | 客户备注,随登录提交给客服侧 |
ext_fk_id | 可选 | 已有访客 ID,用来续上该访客的历史会话 |
referer | 可选 | 来源页 URL(也认 referer_url),客服侧显示为来源链接 |
source_title | 可选 | 来源页标题 |
不要传 visitor_id、source=android / ios / flutter:访客页不读。App 标识用配置项 isApp=true。
会话 API
| 能力 | Android | iOS | Flutter | HarmonyOS |
|---|---|---|---|---|
| 打开独立页 | TwtVisitorSdk.start | TwtVisitorSDK.present | VisitorFlutter.present | TwtVisitorSDK.start |
| 嵌入 | TwtVisitorSdk.embed | makeEmbeddedController | VisitorView | TwtVisitorSDK.embed + VisitorView |
| 切换主题 | handle.setTheme | handle.setTheme | VisitorFlutter.setTheme / handle.setTheme | handle.setTheme |
| 下载回传 | handle.reportDownloadStatus | 同左 | VisitorFlutter.reportDownloadStatus | handle.reportDownloadStatus |
| 关闭 | handle.close() | handle.close() | 宿主 Navigator.pop();present 返回的 handle 在 iOS 上没有关闭能力,改用宿主自建页面 | handle.close()(仅独立页) |
| 清理站点数据 | TwtVisitorSdk.clearSiteData | TwtVisitorSDK.clearSiteData | VisitorFlutter.clearSiteData | TwtVisitorSDK.clearSiteData |
下载状态:started / completed / failed / cancelled。requestId 必须与请求一致。可选字段:path / progress / sourceUrl / mimeType / bytes / errorCode / message。iOS 相册完成路径为 photos://localIdentifier。
清理结果:SUCCESS / INVALID_URL / UNSUPPORTED / IN_USE / FAILED(Flutter 为小写驼峰)。IN_USE 表示仍有会话占用该 host。
HarmonyOS 的 clearSiteData 只清理目标 origin 的 Web Storage:ArkWeb 没有按站点删除 Cookie 的 API,SDK 不做全局 Cookie 清空。
切换账号:关闭页面 → 等待销毁完成 → clearSiteData 成功 → 再打开下一个账号。
回调与事件
回调在主线程。请按 requestId / messageId 去重;页面销毁时把未完成的下载标为 failed。
Android VisitorBridgeListener
onDownloadRequested:开始下载,完成后reportDownloadStatusonNewMessage:新消息onBack():返回键。true表示宿主已处理onPermissionResult:权限结果onTitleChanged:网页标题。SDK 不画标题栏,需要标题的宿主自行展示
iOS VisitorBridgeDelegate(弱引用)
visitorDownloadRequested(...)visitorNewMessage()(可能重复)visitorBack() -> BoolvisitorPermissionResult(...)visitorTitleChanged(_:):网页标题。SDK 不画标题栏,需要标题的宿主自行展示
Flutter VisitorFlutter.events
无监听时不缓存事件,进入页面即 listen,离开时 cancel。
late final StreamSubscription<VisitorBridgeEvent> sub;
@override
void initState() {
super.initState();
sub = VisitorFlutter.events.listen((e) {
switch (e.type) {
case 'downloadRequested':
break;
case 'titleChanged': // payload: {'title': ...}
break;
case 'backRequested': // 原生返回:系统返回键 / iOS 边缘手势
unawaited(_handleBack());
break;
case 'webReady':
case 'webLoadFailed':
case 'close':
case 'new_message':
break;
}
});
}
@override
void dispose() {
sub.cancel();
super.dispose();
}
事件名:downloadRequested、webReady、webLoadFailed、close、backRequested、new_message、titleChanged、theme。
backRequested 是原生侧识别的返回(Android 系统返回键、iOS 边缘手势)。它只上报,不关页面;跟系统返回一样走上面的 handleBack() 判断。(示例里的 unawaited 来自 dart:async。)
嵌入式页面处理返回:
PopScope(
canPop: false,
onPopInvokedWithResult: (_, __) async {
if (!await VisitorFlutter.handleBack()) {
if (context.mounted) Navigator.of(context).pop();
}
},
child: VisitorView(configuration: config),
)
handleBack() == true 表示页面已消费返回(例如从会话详情回到列表)。首次加载失败可调用 VisitorFlutter.reload()。
HarmonyOS VisitorBridgeListener
onDownloadRequested:开始下载,完成后reportDownloadStatusonNewMessage:新消息(铃声为native时)onBack():返回键。true表示宿主已处理onPermissionResult:权限结果onTitleChanged:网页标题。SDK 不画标题栏,需要标题的宿主自行展示
HarmonyOS 的返回 / 下载 / 上传示例方法:
| 场景 | 示例方法 | 位置 |
|---|---|---|
| 独立页返回 | VisitorPage.onBackPress() → VisitorHandle.handleBack() → VisitorView.handleBackRequest() | twt_visitor_sdk/src/main/ets/pages/VisitorPage.ets |
| 嵌入页返回 | 宿主 onBackPress() / 自绘返回键 → session.handleBack(() => ...) | entry/src/main/ets/pages/EmbeddedPage.ets |
| 下载 | DemoListener.onDownloadRequested() → DemoDownloadManager.handleDownload() → copyToTarget() → handle.reportDownloadStatus() | entry/src/main/ets/service/DemoListener.ets、DemoDownloadManager.ets |
| 上传 | VisitorView.onShowFileSelector() → pickFromAlbum() / pickDocuments() → stageForWeb() → finishPicked() | twt_visitor_sdk/src/main/ets/pages/VisitorPage.ets |
| 新消息铃声 | DemoListener.onNewMessage() → DemoRingTonePlayer.play()(通知声道,资源缺失或播放失败降级震动) | entry/src/main/ets/service/DemoListener.ets、DemoRingTonePlayer.ets |
上传由 SDK 内部接管,宿主只要在 module.json5 声明麦克风 / 相机权限;下载必须宿主自己实现,SDK 只把 URL 交出来。
返回处理
访客页是单页应用:返回可能只是关掉图片预览,或从会话详情退回列表,所以要先问页面——页面消费了就留在页面,没消费才关容器。SDK 只负责转发和上报,关不关页面由宿主决定。
| 入口 | 返回由谁处理 | 宿主代码 |
|---|---|---|
Android TwtVisitorSdk.start | SDK 内置 | 不用写;需要二次确认时用 onBack() 拦 |
Android TwtVisitorSdk.embed | 宿主 | visitorView.handleBack { finish() } |
iOS TwtVisitorSDK.present / makeEmbeddedController | 宿主 | 自绘返回键 → handle.close() 或 dismiss |
Flutter VisitorView | 宿主 | PopScope(canPop: false) + VisitorFlutter.handleBack() |
Flutter VisitorFlutter.present | Android 内置 / iOS 宿主 | iOS 改用宿主自建页面 |
HarmonyOS TwtVisitorSDK.start | SDK 内置 | 不用写;需要二次确认时用 onBack() 拦 |
HarmonyOS TwtVisitorSDK.embed + VisitorView | 宿主 | session.handleBack(() => router.back()) |
示例代码:android/sample/.../EmbeddedVisitorActivity.kt、ios/Sample/TwtVisitorSample/MainViewController.swift、visitor_flutter/example/lib/main.dart。
Android
独立页不用写代码:系统返回键和系统手势返回都会进入 Activity 的返回回调 → 问页面 → 页面未消费 → 关 Activity。要在关闭前加一道确认(例如「确认结束咨询」),实现 onBack() 返回 true 即可:
override fun onBack(): Boolean {
showExitConfirmDialog()
return true // 已拦下,SDK 不再关闭页面
}
嵌入页把同样的逻辑接到宿主 Activity 上,自绘返回键也调它:
override fun onBackPressed() {
visitorView.handleBack { finish() }
}
backButton.setOnClickListener { visitorView.handleBack { finish() } }
物理返回键、系统手势返回、自绘返回键都走这一个入口——handleBack 内部已经问过页面(300ms),宿主不用再判断一次。
iOS
原生 SDK 不接管返回,也不转发页面里的 close。返回按钮和左边缘手势都由宿主容器提供,两者调同一个关闭方法:
let visitor = try TwtVisitorSDK.makeEmbeddedController(configuration: config, delegate: self)
visitor.navigationItem.leftBarButtonItem = UIBarButtonItem(
image: UIImage(systemName: "chevron.backward"),
style: .plain,
target: self,
action: #selector(closeVisitor)
)
let container = UINavigationController(rootViewController: visitor)
container.modalPresentationStyle = .fullScreen
// 左边缘手势返回
let edgeBack = UIScreenEdgePanGestureRecognizer(target: self, action: #selector(handleEdgeBack(_:)))
edgeBack.edges = .left
edgeBack.cancelsTouchesInView = false // 不打断点击和滚动
container.view.addGestureRecognizer(edgeBack)
present(container, animated: true)
@objc private func handleEdgeBack(_ gesture: UIScreenEdgePanGestureRecognizer) {
guard gesture.state == .ended else { return }
closeVisitor()
}
@objc private func closeVisitor() { dismiss(animated: true) }
要点:
- SDK 已经把 WebView 自带的
allowsBackForwardNavigationGestures关掉,宿主的边缘手势才不会被 WebView 抢走;宿主自己不要再打开它 present出来的整屏裸页面没有导航栏也没有手势,用户唯一的出口是宿主给的按钮,页面内关闭按钮在 iOS 原生端不生效- 想「先问页面再关」(页面里有图片预览/会话详情),目前原生 iOS 没有公开接口,只能直接关
Flutter
PopScope(
canPop: false, // 先别让系统直接 pop
onPopInvokedWithResult: (didPop, result) {
if (!didPop) unawaited(_handleBack());
},
child: VisitorView(configuration: config),
)
Future<void> _handleBack() async {
if (await VisitorFlutter.handleBack()) return; // 页面消费,留在页面
if (mounted) Navigator.of(context).pop();
}
三种返回都接到 _handleBack():
| 来源 | 怎么到宿主 |
|---|---|
| AppBar 返回箭头 | 默认走 Navigator.maybePop,被 PopScope(canPop: false) 拦下后触发回调 |
| Android 物理返回键 / 系统手势返回 | 同上,走 Flutter 的返回回调 |
| iOS 边缘手势、原生侧识别的返回 | backRequested 事件 |
页面里的关闭按钮走 close 事件,直接 pop。插件内部等页面 300ms(iOS 350ms),超时按未消费处理。
HarmonyOS
独立页不用写代码:VisitorPage 的 onBackPress 会先问页面,未消费再退出。要在关闭前加一道确认,让 listener.onBack 返回 true。
嵌入页把系统返回和自绘返回键都接到同一个方法:
onBackPress(): boolean {
const session = this.session;
if (session === null) {
return false; // 没有会话时交给系统默认处理,避免卡在错误页
}
session.handleBack(() => {
this.getUIContext().getRouter().back();
});
return true;
}
页面里的关闭按钮:独立页由 SDK 转发并退出;嵌入页不转发,由宿主自己的关闭 / 返回按钮处理。
页面侧协议
自己接 WebView、或排查返回没生效时,协议只有三步:
- dispatch
twt:visitor-event,detail.type = 'back' - 页面 300ms(iOS 350ms)内回包:置位
window.__twtVisitorBackConsumed,并通过 AppBridge 调visitor_back_result(params.consumed = true表示已处理,Flutter 插件还会带requestId) - 宿主读
window.__twtVisitorBackConsumed或等visitor_back_result;false/ 超时就关容器
页面侧细节见 访客端 WebView 自行接入 的「系统返回」。
行为说明
导航
同域 HTTPS 留在容器内;跨域 HTTPS 使用系统浏览器;其它 scheme 拦截。
存储
Cookie、LocalStorage、IndexedDB 默认持久化。第三方 Cookie 与混合内容关闭。
权限
仅同域 HTTPS 的麦克风 / 摄像头采集会进入系统授权,跨域一律拒绝。
例外:Flutter 在 Android 上的嵌入页只允许麦克风,摄像头会被拒绝。需要拍摄时请使用独立页或原生 SDK。
HarmonyOS 只允许当前访客页 origin 的采集请求;宿主 HAP 必须自己声明麦克风 / 相机权限。
文件选择
走系统 / WebKit 文件选择器,支持单选与多选。HarmonyOS 由 VisitorView.onShowFileSelector() 接管:图片 / 视频走相册选择器(pickFromAlbum)、文档走文件选择器(pickDocuments);HEIC 等页面 accept 不收的原图经 stageForWeb() 转成 JPEG 再交给页面。
下载
WebView 下载与页面内下载都会回调给宿主,由宿主执行后再回传状态。HarmonyOS 的 ArkWeb 内置下载会被 SDK 取消,只把 URL 交给宿主,避免文件落到临时目录;示例见 VisitorView.setupDownloadDelegate() 与 DemoDownloadManager.handleDownload()。
返回
见「返回处理」。示例:独立页 VisitorPage.onBackPress(),嵌入页 EmbeddedPage.onBackPress() → session.handleBack()。
标题栏
四端容器都是裸 WebView,SDK 不画标题栏。需要标题的宿主通过 onTitleChanged / visitorTitleChanged / titleChanged 事件拿到网页标题,自己在容器外面绘制 AppBar。iOS 用 KVO 盯 webView.title,单页应用切换会话后改标题也会回调;Android 走 onReceivedTitle,HarmonyOS 走 onTitleReceive,同样会随标题变化触发。
键盘与容器视觉
访客页是 100dvh 固定视口,键盘避让靠容器收缩,四端实现不同:
| 平台 | 做法 |
|---|---|
| Android | ime insets 当 padding 加在 VisitorView(FrameLayout)上,VisitorKeyboardAvoidance 用 WindowInsetsAnimationCompat 逐帧插值;收键盘时结合 isVisible(ime) 与 insets 到达先后判断方向;API < 30 交给系统 adjustResize |
| iOS | WKWebView 底约束从 safeAreaLayoutGuide 换成 view.bottomAnchor + 可变常量,keyboardWillChangeFrame 里一次 layoutIfNeeded,不做动画 |
| Flutter | 平台视图自己处理同一套 insets;宿主 Scaffold.resizeToAvoidBottomInset 保持默认(true)时 overlap 恒为 0,实际由 Flutter 缩宿主容器 |
| HarmonyOS | ArkWeb setKeyboardAvoidMode(RESIZE),页面销毁时恢复宿主原来的模式 |
已知代价:改容器尺寸会重建 WebKit / Blink 绘制表面,弹键盘时可能看到一帧闪;彻底消除需要 H5 用 visualViewport 自己避让。Android 的 insets 必须加在父容器上,WebView 自己的 padding 不参与 H5 布局。
容器与 WebView 背景跟随页面 palette:浅色 #F5F7F9、深色 #191919(VisitorChromePolicy.resolvePageBackground、VisitorView 的 paletteColor),避免 resize 和首帧出现白底;iOS 另外 isOpaque = false 并清空 scrollView 背景。
iOS 独立页关闭 scrollView.bounces / alwaysBounceVertical / alwaysBounceHorizontal,固定视口页面不会被拖出回弹空白。
常见问题
为什么打开失败?
检查地址是否为 HTTPS,以及 query 的 key 是否合法。iOS 还会校验 directChatId。
为什么清不掉站点数据?
会话仍在会返回 IN_USE。先关闭全部相关页面,等销毁完成后再清理。iOS 按 host 匹配 WebKit 记录,同一记录下的兄弟子域可能一并清除,但不会做全局清空。
嵌入的 Flutter 页面高度为 0?
给 VisitorView 明确高度,例如包在 Expanded 里。
如何直达某个会话?
设置 directChatId。
如何绑定已登录用户?
在 query 里传 sbs、sbs_mm、ranstr。不要传 visitor_id。
如何在 App 内显示关闭按钮?
isApp = true,页面会显示关闭按钮。点击后:Flutter 会收到 close 事件(宿主自己 pop);HarmonyOS 独立页由 SDK 退出,嵌入页不转发;原生 Android / iOS 目前不转发,需要宿主自绘返回键。
主题如何跟随系统?
初始使用 theme = system。运行中只能切到 light 或 dark。
弱网、后台、锁屏、WebSocket?
请在真机上验证。SDK 不额外封装网络层。
Android 打开时抛 IllegalArgumentException?
start / embed 会立刻校验 URL,空值、非 HTTPS、带 user:pass 都会抛。在按钮回调里 try / catch,把错误提示留在表单里,不要让它冒到主线程。
自绘工具栏被状态栏压住?
targetSdk 35+ 强制 edge-to-edge。给根布局补 WindowInsetsCompat.Type.systemBars() 的 padding(示例里的 applySystemBarInsets())。
自绘标题不居中?
左右两侧留等宽的空间(返回键和占位同宽),标题才会落在屏幕中线上。
iOS 独立页退不出去?
present 是整屏裸 WebView,系统返回手势和关闭按钮都没有。由宿主自绘按钮调用 handle.close() 或 dismiss,或者将 makeEmbeddedController 放进宿主自己的容器。原生 iOS SDK 不转发页面的 close。
HarmonyOS 独立页打不开,日志提示找不到 VisitorPage?
在宿主入口 import 一次 twt_visitor_sdk/src/main/ets/pages/VisitorPage,命名路由才会注册。
HarmonyOS 的 start 为什么返回 null?
URL / query / directChatId 校验失败。空值、非 HTTPS、带 user:pass、非法端口都会返回 null,不会打开页面。
HarmonyOS 为什么清不掉 Cookie?
ArkWeb 没有按站点删除 Cookie 的 API。clearSiteData 只删目标 origin 的 Web Storage,不做全局 Cookie 清空;切换账号请先让页面完成退出。
HarmonyOS 麦克风 / 相机不弹授权?
HAR 的权限声明不会单独生效,宿主 HAP 的 module.json5 必须再声明 ohos.permission.MICROPHONE / ohos.permission.CAMERA。
是否支持截屏桥、图片剪贴板?
不提供截屏桥。图片剪贴板不保证所有系统 WebView 都能使用。
ohpm install twt_visitor_sdk 报包不存在?
确认版本号写的是 0.0.4(中心仓按精确版本拉取),并确认该版本已通过审核。ohpm info twt_visitor_sdk 可查可用版本。
HarmonyOS 编译报 00306046 Bytecode HAR not supported?
HAR 是 bytecode 包,宿主工程 build-profile.json5 必须保持 strictMode.useNormalizedOHMUrl = true。
弹键盘时页面闪一下?
见「行为说明 · 键盘与容器视觉」。容器收缩会重建绘制表面,这是已知代价。