iframe 商品庫跳轉按鈕事件對接

最近更新時間：2026年5月27日

適用場景

本文適用於接入方透過 iframe 將保利威 SaaS 觀看頁嵌入到外部 H5 頁面，並希望在用戶點擊商品庫商品按鈕後，由外部 H5 頁面接收商品點擊事件的場景。

典型訴求包括：

• 接入方 H5 頁面透過 iframe 承載保利威 SaaS 觀看頁。
• 觀看頁內展示商品庫商品。
• 用戶點擊商品按鈕後，外部 H5 頁面需要獲取當前商品資訊。
• 接入方希望在外部 H5 頁面中自行處理埋點、自訂彈窗、跳轉或小程式訊息轉發。

該事件是瀏覽器視窗間的 postMessage 通訊。外部 H5 頁面不監聽該事件時，不影響商品庫原有購買或跳轉邏輯。

事件格式

用戶在 iframe 內點擊商品按鈕後，商品庫會向 iframe 父頁面發送以下事件：

{
  source: 'polyv-product-ui',
  event: 'clickProductButton',
  data: {
    productData: {
      // 当前点击的商品信息
    },
    scene: 'productList'
  }
}

欄位說明：

scene 內置取值如下：

H5 頁面監聽方式

監聽程式碼需要寫在承載 iframe 的外部 H5 頁面中。建議先校驗訊息來源和事件類型，再處理商品資料。

window.addEventListener('message', function (event) {
  const message = event.data || {};

  if (message.source !== 'polyv-product-ui') return;
  if (message.event !== 'clickProductButton') return;

  const productData = message.data && message.data.productData;
  const scene = message.data && message.data.scene;

  console.log('收到商品按钮点击事件：', productData, scene);

  // 可在这里执行接入方自己的业务逻辑
  // 例如：埋点、自定义弹窗、自定义跳转、通知小程序等
});

如果外部 H5 頁面只允許特定觀看頁域名發送訊息，建議結合實際域名校驗 event.origin，避免處理非預期頁面發送的訊息。

小程式 web-view 場景

如果接入方式是「小程式 <web-view> 打開接入方 H5 頁面，接入方 H5 頁面再透過 iframe 嵌入保利威 SaaS 觀看頁」，監聽程式碼仍應寫在接入方 H5 頁面中。小程式頁面本身不能直接監聽 iframe 內部頁面發送的 window.postMessage。

如需繼續通知小程式，可在接入方 H5 頁面收到事件後呼叫 wx.miniProgram.postMessage 轉發。

window.addEventListener('message', function (event) {
  const message = event.data || {};

  if (message.source !== 'polyv-product-ui') return;
  if (message.event !== 'clickProductButton') return;

  if (window.wx && window.wx.miniProgram) {
    window.wx.miniProgram.postMessage({
      data: {
        source: 'polyv-product-ui',
        event: 'clickProductButton',
        productData: message.data && message.data.productData,
        scene: message.data && message.data.scene,
      },
    });
  }
});

在該場景下，如果接入方希望完全由外部 H5 頁面承接商品按鈕後的跳轉鏈路，建議不要配置商品的瀏覽器連結，避免與外部 H5 的自訂處理邏輯重複。

驗證方式

1. 在外部 H5 頁面中透過 iframe 嵌入保利威 SaaS 觀看頁。
2. 在外部 H5 頁面中添加 window.addEventListener('message', handler) 監聽。
3. 在 iframe 內點擊商品庫商品按鈕。
4. 確認監聽器收到 source: 'polyv-product-ui'、event: 'clickProductButton' 的訊息。
5. 確認 data.productData 中包含當前商品資訊，data.scene 能區分點擊來源。

postMessage 是瀏覽器視窗間通訊，不是網路請求，因此無法透過 Charles 等抓包工具直接判斷是否發送成功。建議透過瀏覽器控制台日誌或接入方 H5 頁面中的除錯資訊進行驗證。