跳至主要内容

访客端 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_appApp 内建议 11 时显示关闭按钮,并走 App 返回逻辑
lang可选,默认页面语言界面语言:en / zh-cn / zh-tw / ja / ko / de / fr / pt / ru / es / vi / th / id / ms / tl
theme可选,默认 lightlight / 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;iOS NSMicrophoneUsageDescription / 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_permissionAndroid 录音申请麦克风。回传 { code: 1, data: { permission: true/false } }
visitor_back_result页面应答了返回见「系统返回」

不注入 Bridge 时:关闭按钮无效果;下载走浏览器;铃声由页面自己播。

下载回传​

download 的 params:

字段含义
url文件地址
typeimage / video / 其它
fileName建议文件名
mimeTypeMIME
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' } }
}))