跳至主要内容

TWT Visitor SDK

在 App 内打开访客聊天页面。宿主传入 HTTPS 地址后,SDK 使用系统 WebView / WKWebView / ArkWeb 加载,并处理导航、权限、下载回传与站点数据清理。

不使用 SDK、App 自建 WebView 打开访客页,见 访客端 WebView 自行接入。

当前版本:0.0.4

平台要求集成
AndroidminSdk 23Maven Central:io.github.twt-chat:visitor-sdk:0.0.4
iOSiOS 15+SPM:https://github.com/TWT-Chat/twt-visitor-ios.git(tag 0.0.4,产品 TwtVisitorSDK)
FlutterFlutter ≥ 3.44,Dart ^3.12.0Git:https://github.com/TWT-Chat/visitor_flutter.git(ref 0.0.4)
HarmonyOSHarmonyOS 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 已演示)。


快速开始​

接入方只需搞清三件事:

  1. url(必填):控制台配置的 URL 地址,必须 HTTPS。
  2. 配置项:SDK 认识的字段(isApp / language / theme / directChatId / newMessageSoundMode)。都有默认值,可不传。
  3. 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
isAppfalsetrue 时写 is_app=1App 内打开,访客页显示关闭按钮。false 不写 is_app=0
languagezh-cn每次都写 langen / zh-cn / zh-tw / ja / ko / de / fr / pt / ru / es / vi / th / id / ms / tl
themesystem每次都写 themelight / dark / system。运行时 setTheme 只接受 light / dark
directChatIdnull有值时写 direct=1&chatid=直达会话,并去掉 chat_id
newMessageSoundModeweb一般否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​

能力AndroidiOSFlutterHarmonyOS
打开独立页TwtVisitorSdk.startTwtVisitorSDK.presentVisitorFlutter.presentTwtVisitorSDK.start
嵌入TwtVisitorSdk.embedmakeEmbeddedControllerVisitorViewTwtVisitorSDK.embed + VisitorView
切换主题handle.setThemehandle.setThemeVisitorFlutter.setTheme / handle.setThemehandle.setTheme
下载回传handle.reportDownloadStatus同左VisitorFlutter.reportDownloadStatushandle.reportDownloadStatus
关闭handle.close()handle.close()宿主 Navigator.pop();present 返回的 handle 在 iOS 上没有关闭能力,改用宿主自建页面handle.close()(仅独立页)
清理站点数据TwtVisitorSdk.clearSiteDataTwtVisitorSDK.clearSiteDataVisitorFlutter.clearSiteDataTwtVisitorSDK.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:开始下载,完成后 reportDownloadStatus
  • onNewMessage:新消息
  • onBack():返回键。true 表示宿主已处理
  • onPermissionResult:权限结果
  • onTitleChanged:网页标题。SDK 不画标题栏,需要标题的宿主自行展示

iOS VisitorBridgeDelegate(弱引用)

  • visitorDownloadRequested(...)
  • visitorNewMessage()(可能重复)
  • visitorBack() -> Bool
  • visitorPermissionResult(...)
  • 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:开始下载,完成后 reportDownloadStatus
  • onNewMessage:新消息(铃声为 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.startSDK 内置不用写;需要二次确认时用 onBack() 拦
Android TwtVisitorSdk.embed宿主visitorView.handleBack { finish() }
iOS TwtVisitorSDK.present / makeEmbeddedController宿主自绘返回键 → handle.close() 或 dismiss
Flutter VisitorView宿主PopScope(canPop: false) + VisitorFlutter.handleBack()
Flutter VisitorFlutter.presentAndroid 内置 / iOS 宿主iOS 改用宿主自建页面
HarmonyOS TwtVisitorSDK.startSDK 内置不用写;需要二次确认时用 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、或排查返回没生效时,协议只有三步:

  1. dispatch twt:visitor-event,detail.type = 'back'
  2. 页面 300ms(iOS 350ms)内回包:置位 window.__twtVisitorBackConsumed,并通过 AppBridge 调 visitor_back_result(params.consumed = true 表示已处理,Flutter 插件还会带 requestId)
  3. 宿主读 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 固定视口,键盘避让靠容器收缩,四端实现不同:

平台做法
Androidime insets 当 padding 加在 VisitorView(FrameLayout)上,VisitorKeyboardAvoidance 用 WindowInsetsAnimationCompat 逐帧插值;收键盘时结合 isVisible(ime) 与 insets 到达先后判断方向;API < 30 交给系统 adjustResize
iOSWKWebView 底约束从 safeAreaLayoutGuide 换成 view.bottomAnchor + 可变常量,keyboardWillChangeFrame 里一次 layoutIfNeeded,不做动画
Flutter平台视图自己处理同一套 insets;宿主 Scaffold.resizeToAvoidBottomInset 保持默认(true)时 overlap 恒为 0,实际由 Flutter 缩宿主容器
HarmonyOSArkWeb 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。

弹键盘时页面闪一下?

见「行为说明 · 键盘与容器视觉」。容器收缩会重建绘制表面,这是已知代价。