访客端 WebView 自行接入
App 用自己的 WebView / WKWebView 打开访客页,不接入 Visitor SDK 时按本文对接。HarmonyOS 自建 ArkWeb 的桥接、权限与返回写法可直接参考 visitor_oh/twt_visitor_sdk/src/main/ets/pages/VisitorPage.ets。
优先使用 访客 SDK。本文只覆盖「自己加载页面」。
打开页面
url 填 控制台配置的 URL 地址,必须 HTTPS。业务参数拼在 query 上,自行做 UTF-8 编码。不要把密码、Cookie、AppSecret 或长期 token 放进 URL。
App 内打开建议带 is_app=1,访客页才会显示关闭按钮。
控制台配置的 URL 地址?is_app=1&lang=zh-cn&theme=system
Android:
webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true
webView.loadUrl(buildVisitorUrl())
iOS:
let config = WKWebViewConfiguration()
config.preferences.javaScriptEnabled = true
webView.load(URLRequest(url: visitorURL))
只加载 URL 即可聊天。关闭按钮、原生下载、原生铃声、Android 录音授权需要注入 AppBridge,见下文。
query 参数
| 参数 | 必填? | 含义 |
|---|---|---|
is_app | App 内建议 1 | 1 时显示关闭按钮,并走 App 返回逻辑 |
lang | 可选,默认页面语言 | 界面语言:en / zh-cn / zh-tw / ja / ko / de / fr / pt / ru / es / vi / th / id / ms / tl |
theme | 可选,默认 light | light / dark / system |
direct | 直达会话时必填 1 | 直达开关,没有它时 chatid 无效 |
chatid | 直达会话时必填 | 目标会话 ID(也认 chat_id) |
sbs | 绑用户时必填 | 业务系统里的用户唯一 ID |
sbs_mm | 有 sbs 就要 | sbs 的签名 |
ranstr | 有签名就要 | 参与签名的随机串 |
name | 可选 | 访客姓名 |
nickname | 可选 | 访客昵称 |
email | 可选 | 访客邮箱 |
phone | 可选 | 访客手机号 |
customer_remark | 可选 | 客户备注 |
ext_fk_id | 可选 | 已有访客 ID,用来续历史会话 |
referer | 可选 | 来源页 URL(也认 referer_url) |
source_title | 可选 | 来源页标题 |
new_message_sound_mode | 可选 | native:新消息由 App 响铃;不传则页面自己响 |
不要传 visitor_id。source=webview 效果等同 is_app=1,传一个即可。
WebView 要求
- 启用 JavaScript、DOM Storage
- Cookie / LocalStorage 默认持久化,不要无故清掉(清掉会丢访客身份)
- 仅加载 HTTPS;系统 ATS / Cleartext 保持默认
- 同域麦克风、摄像头:在系统里声明权限(Android
RECORD_AUDIO/CAMERA;iOSNSMicrophoneUsageDescription/NSCameraUsageDescription;HarmonyOS 在宿主 HAP 的module.json5声明MICROPHONE/CAMERA) - 附件选择走 WebView 文件选择器,各端都要自己接(HarmonyOS 为
onShowFileSelector),见「附件上传」 - 同域 HTTPS 留在 WebView;跨域 HTTPS 用系统浏览器
- 容器与 WebView 背景设成页面 palette(浅
#F5F7F9/ 深#191919),否则首帧和尺寸变化会闪白 - iOS 关掉
scrollView.bounces/alwaysBounceVertical/alwaysBounceHorizontal,固定视口页面不会被拖出空白 - 键盘避让加在容器上,见「键盘与视口」
键盘与视口
访客页是 100dvh 固定视口,键盘弹出时页面自己不会让位——要么容器收缩,要么输入框被挡住。
- 容器收缩:键盘 insets 加在容器上,WebView 高度变小。Android 必须加到父
FrameLayout,WebView 自己setPadding不参与 H5 布局计算;ArkWeb 用setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);iOS 改 WKWebView 的底部约束。 - 滚动避让别指望:iOS 关掉
scrollView.bounces/alwaysBounceVertical/alwaysBounceHorizontal,固定视口页面被拖动只会整体回弹露白。 - 底色:容器和 WebView 背景设成页面 palette(浅
#F5F7F9/ 深#191919),iOS 还要isOpaque = false+backgroundColor = .clear,否则收缩和首帧闪一下白。 - 已知代价:改尺寸会重建 WebKit / Blink 的绘制表面,弹键盘时可能有一帧闪。要彻底消除,只能 H5 用
visualViewport自己避让、容器保持不动。
标题栏与返回
不用 SDK 时,标题栏、返回键、关闭按钮全部由 App 自己画,访客页不会在 App 内渲染任何 chrome。
标题
监听 WebView 的标题变化,画到自己的导航栏里:
- Android:
WebChromeClient.onReceivedTitle - iOS:KVO 观察
webView.title。只靠didFinish不够——单页应用切换会话后会再改标题,那里只拿得到首次
返回
用户按返回(Android 系统返回键、iOS 边缘手势、自绘返回按钮)时,先问页面(见「系统返回」),页面未消费再关闭 WebView / 退出当前页。
iOS 边缘手势
要接自己的左边缘滑动手势,先把 webView.allowsBackForwardNavigationGestures 设为 false。WKWebView 自带的返回手势会抢占屏幕边缘的触摸,宿主的 UIScreenEdgePanGestureRecognizer 收不到事件,表现就是「手势没反应」。
Android 安全区
targetSdk 35+ 强制 edge-to-edge。自绘的导航栏要放在 systemBars() inset 之下(给根布局补 padding),否则会被状态栏压住。
附件上传(文件选择器)
访客页用 <input type="file"> 选附件。系统不会替你弹选择器:Android 要覆盖 onShowFileChooser,iOS 要覆盖 runOpenPanelWith,HarmonyOS 要在 Web 的 onShowFileSelector 里返回 true 并自己弹选择器。漏了不报错,用户点一下就「没反应」或者「选了是空的」。
Android
private var pendingCallback: ValueCallback<Array<Uri>>? = null
private val REQ_FILE = 1001
webView.webChromeClient = object : WebChromeClient() {
override fun onShowFileChooser(
view: WebView,
filePathCallback: ValueCallback<Array<Uri>>,
params: FileChooserParams,
): Boolean {
// 上一次没回的结果先取消,否则下一次点选不弹窗
pendingCallback?.onReceiveValue(null)
pendingCallback = filePathCallback
val intent = params.createIntent().addCategory(Intent.CATEGORY_OPENABLE)
intent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, params.mode == FileChooserParams.MODE_OPEN_MULTIPLE)
return runCatching {
startActivityForResult(intent, REQ_FILE)
true
}.getOrElse {
pendingCallback = null
filePathCallback.onReceiveValue(null)
true
}
}
}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode != REQ_FILE) return
val callback = pendingCallback ?: return
pendingCallback = null
if (resultCode != Activity.RESULT_OK) return callback.onReceiveValue(null)
val uris = mutableListOf<Uri>()
data?.data?.let(uris::add) // 单选
data?.clipData?.let { clip -> // 多选
for (i in 0 until clip.itemCount) clip.getItemAt(i).uri?.let(uris::add)
}
callback.onReceiveValue(uris.takeIf { it.isNotEmpty() }?.toTypedArray())
}
要点:
- 一定要复用
FileChooserParams.createIntent()。它带上了页面accept和当前 Activity 的读权限。自己拼ACTION_GET_CONTENT或者用第三方图库也能弹窗,但回传的 URI 页面读不到字节,表现就是「选了但空」。 - 每个
onShowFileChooser必须且只能回一次onReceiveValue。null等于用户取消。漏回,页面 input 会永久卡在等待状态。 - 只认
intent.data和intent.clipData。如果宿主自己有选图/选文件页面,结果只在EXTRA_STREAM里,就要先把文件拷到自己的沙箱,再用FileProvider的content://URI 回传。 - 不要回
file://。宿主一般会关掉allowFileAccess,页面读不到,且 Android 7 起还会抛FileUriExposedException。 - 回传的 URI 必须交给发起
startActivityForResult的那个 Activity,读权限只授给它,换 Activity 就失效。 - 宿主自己的 Activity 里已经接了
onActivityResult的话,注意 requestCode 别撞车。
iOS
func webView(_ webView: WKWebView,
runOpenPanelWith parameters: WKOpenPanelParameters,
initiatedByFrame frame: WKFrameInfo,
completionHandler: @escaping ([URL]?) -> Void) {
let picker = UIDocumentPickerViewController(
forOpeningContentTypes: [.item], asCopy: true) // asCopy 直接给沙箱副本
picker.allowsMultipleSelection = parameters.allowsMultipleSelection
picker.delegate = self
self.openPanelCompletion = completionHandler
present(picker, animated: true)
}
func documentPicker(_ controller: UIDocumentPickerViewController, didPickDocumentsAt urls: [URL]) {
defer { openPanelCompletion = nil }
guard let completion = openPanelCompletion else { return }
// 安全作用域外的 URL 先拷进 tmp,否则 WebKit 读到 0 字节
let copied = urls.compactMap(copyToTemporaryDirectory)
completion(copied.isEmpty ? nil : copied)
}
func documentPickerWasCancelled(_ controller: UIDocumentPickerViewController) {
openPanelCompletion?(nil)
openPanelCompletion = nil
}
要点:
- 不实现
runOpenPanelWith就没有文件选择器,点「上传」什么都不会发生(WKUIDelegate只需声明不够,必须真的实现这个方法)。 completion只能调用一次,取消时传nil。- iCloud、文件 App 里的文件是安全作用域的,不调
startAccessingSecurityScopedResource()或者不先拷贝到NSTemporaryDirectory(),WebKit 拿到 URL 也读不到内容,上传就是 0 字节。用asCopy: true最省事。 - 想用相册选图(
PHPickerViewController)、拍照也行,但拿到的不是文件 URL,要先编码成临时文件再回传,不能把UIImage或者相册 item 标识直接丢给completion。
HarmonyOS
示例方法:VisitorView.onShowFileSelector() → pickFromAlbum() / pickDocuments() → stageForWeb() → finishPicked()(见 visitor_oh/twt_visitor_sdk/src/main/ets/pages/VisitorPage.ets)。
Web({ src: url, controller: this.controller })
.onShowFileSelector((event: OnShowFileSelectorEvent) => {
this.onShowFileSelector(event);
return true; // true:宿主自己弹选择器;false 会退回 ArkWeb 默认实现
})
private onShowFileSelector(event: OnShowFileSelectorEvent): void {
const accept = event.fileSelector.getAcceptType();
const multiple = event.fileSelector.getMode() === FileSelectorMode.FileOpenMultipleMode;
// 图片/视频走相册:文档选择器选不到图库,HEIC 原图页面还会丢掉
const wantsMedia = accept.some((t: string) => t.startsWith('image/') || t.startsWith('video/'));
if (wantsMedia) {
this.pickFromAlbum(event.result, accept, multiple);
} else {
this.pickDocuments(event.result, multiple);
}
}
要点:
- 必须
return true。返回false时 ArkWeb 用自带选择器,回给页面的是它自己的临时路径,宿主拿不到文件。 event.result.handleFileList(uris)只能回一次。取消要回空数组[],漏回会让页面input永久等待。- 相册返回的
file://media/Photo/...是一次性授权,先fs.copyFile到沙箱,再用fileUri.getUriFromPath生成 Web 能读的 URI。 - 页面
accept里没有heic/heif时,相册原图要先image.createImageSource+packing转 JPEG 再回传,否则选完是空的。 - 文档选择器给的
file://docs/...同样先拷贝到沙箱,不能直接把 docs URI 交给页面。 - 相册 / 相机权限要在宿主 HAP 的
module.json5声明,HAR 里的声明不会单独生效。
各端都要注意
- HEIC:访客页
accept里没有heic/heif,iOS 相册原图、部分 Android 相册直接给 HEIC 时,URI 有效但页面会静默丢掉。要让用户传相册原图,就先转成 JPEG(或另存一份 JPEG)再回传。 - 体积:SDK 不代为压缩,超大文件由页面自己处理;宿主可以在回传前做一次上限检查并给提示。
选完是空文件,怎么查
| 现象 | 常见原因 |
|---|---|
| 点上传没反应 | iOS 没实现 runOpenPanelWith;Android 上一次 onReceiveValue 没回;HarmonyOS onShowFileSelector 没返回 true 或没回 handleFileList |
| 选了文件,input 里还是空 | 取消或 data 为空时回了 null;URI 只在 EXTRA_STREAM 里没读 |
| 有文件名,上传 0 字节 | Android 回了 file://;URI 的读权限不在当前 Activity;iOS 安全作用域 URL 没拷贝 |
| 相册图片选了没进列表 | HEIC 被页面 accept 过滤 |
AppBridge
页面通过 window.AppBridge.call(method, params, callback) 调 App。页面每次加载前注入下面脚本(建议 atDocumentStart,不要等 onPageFinished)。
(function () {
window.__TWT_VISITOR_BRIDGE_CONFIG__ = { newMessageSoundMode: 'web' };
window.AppBridge = {
_callbacks: {},
call: function (method, params, callback) {
var id = callback ? 'cb_' + Date.now() + '_' + Math.random().toString(16).slice(2) : null;
if (callback) this._callbacks[id] = callback;
var msg = JSON.stringify({ method: method, params: params || {}, callback: id });
if (window.AppBridgeChannel_native) {
window.AppBridgeChannel_native.postMessage(msg);
} else if (window.webkit && window.webkit.messageHandlers.AppBridgeChannel) {
window.webkit.messageHandlers.AppBridgeChannel.postMessage(msg);
}
return Promise.resolve({ status: 'sent', callbackId: id });
},
invokeCallback: function (id, result) {
var cb = this._callbacks[id];
if (cb) { cb(result); delete this._callbacks[id]; }
}
};
})();
Android 注册名为 AppBridgeChannel_native 的 JavascriptInterface(方法名 postMessage)。
iOS 注册名为 AppBridgeChannel 的 WKScriptMessageHandler。HarmonyOS 用 javaScriptProxy 注册同名通道,示例见 VisitorView 的 proxy 与 bridgeScript。
消息 JSON:{ "method": "...", "params": {}, "callback": "cb_..." }。
页面会调用的方法
| method | 何时 | App 做什么 |
|---|---|---|
close | 用户点页面关闭按钮 | 关闭 WebView / 退出当前页 |
download | 保存图片、视频、文件 | 下载 params.url;完成后见下方回传 |
new_message | 收到新消息且铃声为 native | 播放提示音。params 可能含 messageId / chatId |
android_recording_permission | Android 录音 | 申请麦克风。回传 { code: 1, data: { permission: true/false } } |
visitor_back_result | 页面应答了返回 | 见「系统返回」 |
不注入 Bridge 时:关闭按钮无效果;下载走浏览器;铃声由页面自己播。
下载回传
download 的 params:
| 字段 | 含义 |
|---|---|
url | 文件地址 |
type | image / video / 其它 |
fileName | 建议文件名 |
mimeType | MIME |
requestId | 本次下载 ID |
有 callback 时,下载结束调用:
window.AppBridge.invokeCallback(callbackId, {
code: 1,
data: { requestId: '...', status: 'completed' }
})
status:completed / failed / cancelled。失败时 code 用 0。
HarmonyOS 的 ArkWeb 会自己开始下载,必须用 WebDownloadDelegate.onDownloadStart 拦下并 item.cancel(),再把 item.getUrl() / getMimeType() / getSuggestedFileName() 交给宿主,示例见 VisitorView.setupDownloadDelegate()。不取消也能下,但文件落在 ArkWeb 临时目录,系统会弹一条无关的「下载完成」。
若要把铃声交给 App,注入时把 newMessageSoundMode 设为 'native',或 URL 带 new_message_sound_mode=native。
系统返回(可选)
用户按系统返回时,先问页面(关闭预览、从会话退回列表):
window.dispatchEvent(new CustomEvent('twt:visitor-event', {
detail: { type: 'back', payload: {} }
}))
页面收到后会把处理结果写两处:window.__twtVisitorBackConsumed 置为 true/false,并通过 AppBridge 调 visitor_back_result(params.consumed)。宿主只要读一处即可。约 300ms(iOS 350ms)内没有回包就按「未处理」处理,别无限等。
Android:
webView.evaluateJavascript(
"(function(){window.__twtVisitorBackConsumed=false;" +
"window.dispatchEvent(new CustomEvent('twt:visitor-event',{detail:{type:'back',payload:{}}}));})()",
null,
)
Handler(Looper.getMainLooper()).postDelayed({
webView.evaluateJavascript("!!window.__twtVisitorBackConsumed") { raw ->
if (raw != "true") finish() // 页面没消费才关
}
}, 300)
iOS:
let js = "window.__twtVisitorBackConsumed=false;" +
"window.dispatchEvent(new CustomEvent('twt:visitor-event',{detail:{type:'back',payload:{}}}))"
webView.evaluateJavaScript(js) { _, _ in
DispatchQueue.main.asyncAfter(deadline: .now() + 0.35) {
webView.evaluateJavaScript("!!window.__twtVisitorBackConsumed") { result, _ in
if (result as? Bool) != true { dismiss(animated: true) }
}
}
}
HarmonyOS(示例 VisitorView.handleBackRequest()):
this.controller.runJavaScript(
"window.__twtVisitorBackConsumed=false;" +
"window.dispatchEvent(new CustomEvent('twt:visitor-event',{detail:{type:'back',payload:{}}}))",
);
setTimeout(() => {
this.controller.runJavaScript('!!window.__twtVisitorBackConsumed').then((raw: string) => {
if (raw !== 'true') {
this.getUIContext().getRouter().back(); // 页面没消费才关
}
});
}, 300);
自绘返回键、Android 系统返回键、iOS 边缘手势、HarmonyOS 系统返回(onBackPress)都接到同一个函数上。iOS 记得先关掉 allowsBackForwardNavigationGestures,否则边缘手势会被 WebView 抢走。
运行中切主题(仅 light / dark):
window.dispatchEvent(new CustomEvent('twt:visitor-event', {
detail: { type: 'themeChanged', payload: { theme: 'dark' } }
}))