反馈组件 · 接入

1先试一下

右边是真的在跑的组件，不是效果图。在左边假装是「桐桐画坊」的窗口里画两笔， 然后拖动右下角的「反馈」按钮、点它 —— 看它抓走了什么。

2把这一行贴进你的项目

贴在 </body> 之前就行。它会自动把现场采集、表单、样式一起拉起来，你不需要额外引任何东西。 凭证（data-zy-key）不用申请：后台 → 建项目/版本 → 版本详情 →「包内反馈入口」一键生成（一版一个，稳定不变）；上面第 1 节选好版本，这里的代码会自动填上真凭证。

3两种触发，对应两种版本

连击判定：1.6 秒内 5 次，每一下都要落在起点 26px 以内 —— 边走边点不会误触发。桌面浏览器用鼠标连点 5 下等效。

4点下去的那一刻，系统自动带走了什么

5原生壳想要「真·全屏截图」

页面快照只能拿到 WebView 里的内容。如果你想要一张连原生界面一起的全屏截图， 让原生侧接一根桥即可 —— 协议只有一句话：我们喊一声，你把图回灌给我们。

// 1. 注册桥。网页侧会 postMessage {cmd:"shot"}
let script = """
window.addEventListener('DOMContentLoaded', function () {
  window.webkit.messageHandlers.zyfb && null;
});
"""
let ucc = WKUserContentController()
ucc.add(self, name: "zyfb")          // 网页喊的就是这个名字
cfg.userContentController = ucc

// 2. 收到喊话 → 截图 → 回灌
func userContentController(_ uc: WKUserContentController,
        didReceive message: WKScriptMessage) {
  guard (message.body as? [String: Any])?["cmd"] as? String == "shot" else { return }
  let cfg = WKSnapshotConfiguration()
  webView.takeSnapshot(with: cfg) { image, _ in
    guard let d = image?.jpegData(compressionQuality: 0.72) else { return }
    let b64 = "data:image/jpeg;base64," + d.base64EncodedString()
    webView.evaluateJavaScript(
      "window.ZYSnapshot && window.ZYSnapshot.attach('\(b64)')")
  }
}

// 1. 暴露桥对象
webView.addJavascriptInterface(object {
  // 组件会调用这个方法
  @JavascriptInterface fun shot() {
    webView.post {
      val bmp = Bitmap.createBitmap(webView.width, webView.height, Bitmap.Config.ARGB_8888)
      webView.draw(Canvas(bmp))                    // 含 WebView 内的全部渲染结果
      val bos = ByteArrayOutputStream()
      bmp.compress(Bitmap.CompressFormat.JPEG, 72, bos)
      val b64 = Base64.encodeToString(bos.toByteArray(), Base64.NO_WRAP)
      webView.post {
        webView.evaluateJavascript(
          "window.ZYSnapshot \&\& window.ZYSnapshot.attach('data:image/jpeg;base64,$b64')", null)
      }
    }
  }
}, "ZYFeedbackAndroid")

// 2. 想要连状态栏一起拍，用 MediaProjection；只在 WebView 内就够的话上面这段已经是了

接上桥之后，组件会优先用原生给的那张图。900 毫秒内没等到就自动退回页面快照 —— 原生侧不该让用户卡在提交页上。

整个页面都是纯原生（没有 WebView）？不走组件，直接打 POST /api/v1/reports（对任意来源开放、匿名）。字段与组件提交的完全一致，截图原生侧自己截 （SwiftUI ImageRenderer / Compose View.draw），转 data URL 塞进 media； 摇一摇等原生手势唤面板用 evaluateJavascript("window.ZYFeedback.open()")。

POST /api/v1/reports                  Content-Type: application/json
{ "feedbackKey": "FK-…",          // 后台版本详情里生成的凭证，决定反馈挂到哪一版
  "steps": "1. … 2. …",           // 复现方法（带凭证时 steps / actual 至少一个要有内容）
  "actual": "哪不对",
  "version": "1.4.0-beta.3",
  "reporter": { "channel": "native-ios" },
  "env": { "model": "iPhone16,2", "os": "iOS 20.0" },
  "media": [ { "kind": "shot", "mime": "image/jpeg", "name": "01-autoshot.jpg",
               "data": "data:image/jpeg;base64,…" } ] }   // ≤12 张、每张 ≤8MB

6接上了没？一行自检

fetch('/api/v1/onsite/check?key=FK-XXXXX-XXXXX')
  .then(r => r.json()).then(console.log)