商品卡片与订单卡片对接文档

1. 概述

客服 H5 支持展示商品卡片和订单卡片。用户点击卡片后，若卡片配置 crossApp: true，H5 会根据 URL 参数 embedded 将点击交给宿主容器处理。

2. 卡片数据

2.1 商品卡片

发送消息时，消息类型为 goodsCard，消息内容为 JSON 字符串或对象。

{
  "img": "https://example.com/goods.png",
  "title": "真皮手提包",
  "desc": "黑色，标准款",
  "remark": "支持七天无理由退货",
  "url": "/pages/goods-detail/index?goodsId=10001",
  "crossApp": true
}

2.2 订单卡片

发送消息时，消息类型为 ordersCard，消息内容为 JSON 字符串或对象。

{
  "orderNo": "2026080800123456",
  "payAmount": 399,
  "orderTime": "2026-04-30",
  "status": "已发货",
  "shopName": "淘宝AA商户",
  "products": [
    {
      "name": "订单商品 1",
      "image": "https://example.com/goods-1.png",
      "spec": "颜色分类：原木色；商品规格 1"
    }
  ],
  "remark": "请发顺丰，工作日白天有人签收",
  "url": "/pages/order-detail/index?orderNo=2026080800123456",
  "crossApp": true
}

3. 通过 H5 URL 预置卡片

可通过 H5 地址参数预置待发送的卡片。content 必须进行 URL 编码。

https://your-h5-host/ue?channelId=CHANNEL_ID&embedded=wechatMiniProgram&contentType=ordersCard&content=%7B...%7D

参数说明：

4. 微信小程序对接

4.1 H5 地址

小程序 web-view 的 H5 地址必须带上：

embedded=wechatMiniProgram

4.2 跳转规则

微信小程序渠道点击卡片时，H5 会直接执行：

wx.miniProgram.navigateTo({
  url: content.url
})

因此 url 必须满足以下条件：

• 必须是已注册的小程序原生页路径。
• 必须以 / 开头，例如 /pages/order-detail/index?orderNo=2026080800123456。
• 不能是 https:// 或 http:// 地址。
• 不能带 .js 后缀。
• 目标页面必须已写入小程序 app.json 的 pages。

小程序目标页示例：

Page({
  onLoad(options) {
    console.log("订单详情页参数:", options)
  }
})

4.3 小程序配置示例

{
  "pages": [
    "pages/webview/index",
    "pages/order-detail/index",
    "pages/goods-detail/index"
  ]
}

微信小程序渠道不使用 wx.miniProgram.postMessage 传递卡片点击事件，因为其消息只会在后退、销毁或分享等特定时机投递，无法即时处理点击。

5. 其他宿主点击协议

除微信小程序外，卡片点击事件名称统一为：

goodsCardClick

事件中携带完整的商品卡片或订单卡片对象。

5.1 uni-app

普通 web-view：

// H5 发送的数据
{
  data: {
    action: "goodsCardClick",
    params: card
  }
}

App-Plus 环境优先发送全局事件 ueGoodsCardClick：

{
  action: "goodsCardClick",
  params: card
}

5.2 Flutter

H5 调用：

window.flutter_inappwebview.callHandler("goodsCardClick", card)

5.3 Android WebView

H5 调用：

window.Android.goodsCardClick(JSON.stringify({
  params: card,
  callback: null
}))

5.4 iOS WKWebView

H5 调用：

window.webkit.messageHandlers.goodsCardClick.postMessage({
  params: card,
  callback: null
})

5.5 iframe

H5 向父页面发送 goodsCardClick 及完整卡片对象。父页面应监听 message 事件并按自身业务处理。

6. 排查清单

1. 确认卡片配置 crossApp: true。
2. 确认卡片存在非空 url。
3. 微信小程序中确认 H5 URL 包含 embedded=wechatMiniProgram。
4. 微信小程序中确认 url 是 /pages/... 原生页面路径，且目标页已注册。
5. 使用 H5 WebView 调试控制台查看 [ueChat] 日志；小程序 Page Console 不会显示 H5 的 console.log。
6. 查看 wx.miniProgram.navigateTo 的失败日志，确认是否为页面未注册、页面栈超过限制或路径错误。