跳到主要内容

事件对接 API (postMessage)

当 VCMS 组件被 iframe 嵌入到你的平台时，组件可以把用户的交互（点「更多」、点视频）通过浏览器原生的 window.postMessage 抛给父页面，由你的平台决定怎么处理。

跨域安全：iframe 与父页面不同源也能通信，这是 postMessage 的标准用法。

两种模式​

在嵌入 URL 上加 events 参数来启用：

模式URL 参数行为
只发事件?events=1组件不跳转，只把事件抛给父页面。你的平台自己处理（开新窗口播放、走自家路由、弹窗等）。
跳转 + 发事件?events=nav组件自己跳转到门户（整页），同时发事件给你（用于埋点/统计）。
不启用（不加 events）默认行为：组件用 target="_top" 自己跳转，不发事件。

events=nav 会在发出事件后约 120ms 再跳转，确保你的监听函数（如埋点）先执行。

嵌入示例​

<!-- 只发事件：你的平台全权处理交互 -->
<iframe src="https://vcms-qa.acorners.com/strip?platform=1&events=1"
        width="100%" height="300" frameborder="0" scrolling="no"></iframe>

<!-- 跳转 + 发事件：组件自己跳门户，你只做埋点 -->
<iframe src="https://vcms-qa.acorners.com/strip?platform=1&events=nav"
        width="100%" height="300" frameborder="0" scrolling="no"></iframe>

events 参数对横条 /strip、完整页 /embed 都生效。

消息格式​

每个事件都是一个对象，通过 window.parent.postMessage(payload, '*') 发出。所有事件都带 source: 'vcms'，请用它过滤，避免和页面里其它 message 混淆。

interface VcmsEvent {
  source: 'vcms';
  type: 'video:click' | 'more:click';
  // 其余字段随 type 不同，见下表
  [key: string]: unknown;
}

事件清单​

video:click — 用户点了某个视频​

字段类型说明
source'vcms'固定值
type'video:click'事件类型
videoIdstring视频 ID
titlestring视频标题
watchUrlstring该视频的播放页完整地址（打开后自动播放）
{
  "source": "vcms",
  "type": "video:click",
  "videoId": "dcfc79f8-5650-4f6f-9416-3161e33f7af6",
  "title": "APB 品牌宣传片",
  "watchUrl": "https://vcms-qa.acorners.com/watch/dcfc79f8-5650-4f6f-9416-3161e33f7af6"
}

more:click — 用户点了「更多」​

字段类型说明
source'vcms'固定值
type'more:click'事件类型
urlstring视频中心「全部」的完整地址
{
  "source": "vcms",
  "type": "more:click",
  "url": "https://vcms-qa.acorners.com/"
}

接入（父页面监听）​

在嵌入了 iframe 的页面里加一个 message 监听，按 type 处理：

<script>
  window.addEventListener('message', (e) => {
    // 1) 只认 VCMS 的事件
    if (!e.data || e.data.source !== 'vcms') return;

    // 2)（推荐）校验来源域名，更安全
    // if (e.origin !== 'https://vcms-qa.acorners.com') return;

    switch (e.data.type) {
      case 'video:click':
        // 例：在新窗口打开播放页
        window.open(e.data.watchUrl, '_blank');
        // 或：埋点统计
        // track('video_click', { id: e.data.videoId, title: e.data.title });
        break;

      case 'more:click':
        // 例：跳转到视频中心
        location.href = e.data.url;
        break;
    }
  });
</script>

怎么选模式？​

  • 想自己掌控点击后的行为（开新窗口、在你的 SPA 里路由、先弹个确认框）→ 用 events=1，在监听里自己处理 watchUrl / url。
  • 只想记录用户点了什么、跳转交给组件 → 用 events=nav，监听里只做埋点，组件会自己跳。

安全与注意事项​

  • 过滤 source：始终先判断 e.data.source === 'vcms'，页面里可能有别的 postMessage。
  • 校验 e.origin（推荐）：生产环境建议再加一道 e.origin === '你的VCMS门户域名'，防止伪造。
  • 防盗链：你的域名需在允许 referrer 白名单内（请联系我们开通），否则视频/缩略图会 403。
  • 自动播放：watchUrl 打开后会尝试自动播放；浏览器的自动播放策略可能要求静音或一次用户交互，这是浏览器层面的限制。
  • targetOrigin：组件用 '*' 发送，因此接收方务必自己校验 e.data.source（和可选的 e.origin）。

在线体验​

VCMS 后台 「教学」 页底部的「事件对接」一节有一个实时模拟：嵌入一个 events=1 的组件，点「更多」或视频就能在右边实时看到收到的事件 JSON，并附有可复制的嵌入代码与监听代码。