iframe Product Library Jump Button Event Integration

Last updated: May 27, 2026

Applicable Scenarios

This document applies to scenarios where the integrator embeds the Polyv SaaS viewing page into an external H5 page via iframe, and expects the external H5 page to receive product click events when users click product library buttons.

Typical requirements include:

• The integrator's H5 page hosts the Polyv SaaS viewing page via iframe.
• The viewing page displays products from the product library.
• When a user clicks a product button, the external H5 page needs to obtain the current product information.
• The integrator wishes to handle tracking, custom popups, redirects, or mini-program message forwarding within the external H5 page.

This event uses postMessage communication between browser windows. If the external H5 page does not listen for this event, the original purchase or redirect logic of the product library remains unaffected.

Event Format

When a user clicks a product button inside the iframe, the product library sends the following event to the iframe's parent page:

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

Field Description:

scene built-in values are as follows:

H5 Page Listening Method

The listening code should be written in the external H5 page that hosts the iframe. It is recommended to first verify the message source and event type before processing product data.

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);

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

If the external H5 page only allows messages from specific viewing page domains, it is recommended to validate event.origin against the actual domain to avoid processing messages from unintended pages.

Mini-Program web-view Scenario

If the integration method is "mini-program <web-view> opens the integrator's H5 page, and the integrator's H5 page then embeds the Polyv SaaS viewing page via iframe", the listening code should still be written in the integrator's H5 page. The mini-program page itself cannot directly listen for window.postMessage sent from within the iframe.

If forwarding to the mini-program is required, call wx.miniProgram.postMessage in the integrator's H5 page after receiving the event.

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,
      },
    });
  }
});

In this scenario, if the integrator wants the external H5 page to fully handle the redirect chain after a product button click, it is recommended not to configure a browser link for the product, to avoid duplication with the external H5 page's custom processing logic.

Verification Method

1. Embed the Polyv SaaS viewing page via iframe in the external H5 page.
2. Add window.addEventListener('message', handler) listener in the external H5 page.
3. Click a product library button inside the iframe.
4. Confirm that the listener receives a message with source: 'polyv-product-ui' and event: 'clickProductButton'.
5. Confirm that data.productData contains the current product information, and data.scene can distinguish the click source.

postMessage is communication between browser windows, not a network request, so it cannot be directly verified using packet capture tools like Charles. It is recommended to verify via browser console logs or debug information in the integrator's H5 page.