Polyv 影片創作頁面嵌入與通訊協定

更新時間：2026-06-16 17:42:09

文件版本： v1.1 最後更新： 2026 年 6 月 16 日

1. 概述

本文件旨在協助開發者將保利威 (Polyv) AI 影片創作功能以 iframe 的形式無縫整合至第三方業務平台。透過遵循本文件中的指引，您可以實現：

介面客製化：透過 URL 參數控制嵌入頁面中特定按鈕的顯示與隱藏。
功能呼叫：使用 Window.postMessage API，在您的父頁面與 Polyv 的 iframe 頁面之間建立安全通訊，以程式化方式觸發影片生成、草稿儲存等操作。

本文件適用於需要在自有產品中提供 AI 影片創作能力，並希望對整合介面與流程進行自訂控制的客戶。

2. 快速開始

要實現基礎的嵌入與通訊，您需要以下兩個步驟：

嵌入 iframe：將 Polyv AI 影片創作頁面的 iframe 放置在您的頁面中。
實作通訊腳本：編寫 JavaScript 程式碼，用於監聽 iframe 的就緒狀態，並發送指令。

以下是一個基本的 HTML 結構範例：

<!DOCTYPE html>
<html>
<head>
  <title>集成 Polyv AI 视频创作</title>
</head>
<body>

  <!-- 1. 嵌入 Polyv AI 视频创作编辑页面 -->
  <iframe
    src="https://console.polyv.net/live/index.html#/ai-manager/video-production/create"
    frameborder="0"
    id="polyvAiFrame"
    style="width: 100%; height: 800px;">
  </iframe>

  <!-- 2. 父页面的控制按钮 -->
  <button id="createVideoButton" type="button">从外部触发生成</button>
  <button id="returnButton" type="button">返回</button>

  <!-- 3. 通信脚本 -->
  <script>
    // 详细逻辑见下文
  </script>

</body>
</html>

3. 功能詳解

3.1. 介面客製化 (URL 參數)

您可以透過在 iframe 的 src 屬性連結後附加特定參數，來客製化嵌入頁面的外觀。此方式靈活且易於實作。

參數列表

參數	類型	描述	範例
`video-production-submit`	String	`N`：隱藏頁面右上角的【生成影片】按鈕。	`...create?video-production-submit=N`
`video-production-return`	String	`N`：隱藏頁面左上角的【返回】按鈕。	`...create?video-production-return=N`

組合使用範例

若要同時隱藏「生成影片」與「返回」按鈕，可以這樣配置 src：

<iframe
  src="https://console.polyv.net/live/index.html#/ai-manager/video-production/create?video-production-submit=N&video-production-return=N"
  id="polyvAiFrame">
</iframe>

3.2. 互動通訊 (PostMessage API)

為了實現父頁面對 iframe 內操作的精準控制，我們定義了一套基於 postMessage 的雙向通訊協定。

核心流程：

Iframe 頁面載入完成後，會向父頁面發送一個 ready 狀態通知。
父頁面監聽到 ready 通知後，即可確認 iframe 已準備就緒。
此後，父頁面可以向 iframe 發送 create、save-draft 等具體指令。
Iframe 成功提交生成任務後，向父頁面發送 submit-success 事件通知。
當接入方隱藏 iframe 內建【返回】按鈕，並使用父頁面自己的【返回】按鈕時，父頁面可先向 iframe 發送 save-draft，等待 iframe 返回草稿儲存結果後，再執行自身返回邏輯。

JavaScript 通訊邏輯實作

const $iframe = document.getElementById('polyvAiFrame');
const $createVideoButton = document.getElementById('createVideoButton');
const $returnButton = document.getElementById('returnButton');
const targetOrigin = 'https://console.polyv.net';
let isFrameReady = false;

$createVideoButton.disabled = true;
$returnButton.disabled = true;

// 监听来自 iframe 的消息
window.addEventListener('message', (event) => {
  // 安全校验：确保消息来自指定的源
  if (event.origin !== targetOrigin) {
    return;
  }

  try {
    const data = JSON.parse(event.data);

    // 只处理 Polyv AI 视频创作协议消息
    if (data.type !== 'ai-video-production') {
      return;
    }

    // ready：iframe 已完成初始化，可以接收父页面指令
    if (data.type === 'ai-video-production' && data.event === 'ready') {
      isFrameReady = true;
      console.log('Polyv AI iframe 已准备就绪。');
      // 可在此处启用相关按钮
      $createVideoButton.disabled = false;
      $returnButton.disabled = false;
      return;
    }

    // save-draft：iframe 返回草稿保存结果
    if (data.type === 'ai-video-production' && data.event === 'save-draft') {
      if (data.success) {
        console.log('草稿保存成功，可以执行父页面返回逻辑。');
        // TODO: 在这里执行接入方系统自己的返回逻辑
        // window.history.back();
      } else {
        console.warn('草稿保存失败：', data.message || 'Fail reason');
        // TODO: 在这里提示用户，父页面不应自动返回
      }
    }

    // submit-success：视频生成任务已提交到后台处理队列
    if (data.type === 'ai-video-production' && data.event === 'submit-success') {
      console.log('视频生成任务已提交。');
    }
  } catch (error) {
    console.warn('无法解析来自 iframe 的消息：', error);
  }
});

// 为父页面的按钮绑定点击事件
$createVideoButton.addEventListener('click', () => {
  if (!isFrameReady) {
    alert('视频创作页面尚未准备好，请稍候...');
    return;
  }

  // create：请求 iframe 启动视频生成流程
  const message = {
    type: 'ai-video-production',
    event: 'create'
  };

  // 向 iframe 发送“生成视频”指令
  $iframe.contentWindow.postMessage(JSON.stringify(message), targetOrigin);
});

$returnButton.addEventListener('click', () => {
  if (!isFrameReady) {
    alert('视频创作页面尚未准备好，请稍候...');
    return;
  }

  // save-draft：请求 iframe 保存当前编辑内容的草稿
  const message = {
    type: 'ai-video-production',
    event: 'save-draft'
  };

  // 向 iframe 发送“保存草稿”指令，等待 iframe 返回保存结果后再执行父页面返回逻辑
  $iframe.contentWindow.postMessage(JSON.stringify(message), targetOrigin);
});

4. 通訊協定規範

所有通訊訊息均為 JSON 字串格式，且 type 固定為 ai-video-production。草稿儲存協定中，父頁面發起請求與 iframe 返回結果均使用 save-draft 事件；父頁面發起請求時不攜帶 success，iframe 返回結果時攜帶 success 與 message。

4.1. Iframe → 父頁面

`event` 值	描述	訊息體 (Payload) 範例
`ready`	通知父頁面，iframe 已載入完畢，可以接收指令。這是一個關鍵的「握手」訊號。	`{"type": "ai-video-production", "event": "ready"}`
`submit-success`	通知父頁面，當影片生成任務成功提交到後台處理佇列後，通知父頁面。表示使用者的請求已被接受	`{"type": "ai-video-production", "event": "submit-success"}`
`save-draft`	通知父頁面，本次草稿儲存結果已返回，父頁面可根據 `success` 判斷是否繼續執行自己的返回邏輯。	`{"type": "ai-video-production", "event": "save-draft", "success": true

4.2. 父頁面 → Iframe

`event` 值	描述	訊息體 (Payload) 範例
`create`	請求 iframe 啟動影片生成流程。其效果等同於點擊 iframe 內的【生成影片】按鈕。	`{"type": "ai-video-production", "event": "create"}`
`save-draft`	請求 iframe 執行當前編輯內容的草稿儲存。該動作通常由接入方自己的【返回】按鈕觸發。	`{"type": "ai-video-production", "event": "save-draft"}`

4.3. 草稿儲存與外部返回流程

當接入方透過 video-production-return=N 隱藏 iframe 頁面左上角【返回】按鈕，並使用父頁面自己的【返回】按鈕時，應按以下流程處理：

使用者點擊接入方系統自己的【返回】按鈕。
父頁面確認已收到 iframe 的 ready 事件後，向 iframe 發送 save-draft。
Iframe 執行當前編輯內容的草稿儲存。
Iframe 向父頁面回調 save-draft，並透過 success 表達儲存結果。
當 success 為 true 時，父頁面可以繼續執行自己的返回邏輯。
當 success 為 false 時，父頁面不應自動返回；建議根據 message 提示使用者或記錄日誌。

若當前頁面沒有新的未儲存變更，iframe 仍應回調 save-draft，並返回 success: true。父頁面不需要額外判斷當前是否存在未儲存變更。

5. 重要注意事項

安全策略：在 addEventListener 中，務必嚴格校驗 event.origin，確保訊息來源是 https://console.polyv.net。在 postMessage 時，也應明確指定 targetOrigin，避免使用 *，防止敏感資料外洩。
載入時序：父頁面必須等待並確認收到 iframe 的 ready 事件後，才能發送業務指令（如 create、save-draft）。建議在收到 ready 訊號前，將父頁面的控制按鈕設定為停用狀態。
訊息格式：所有通訊資料都必須透過 JSON.stringify() 序列化為字串進行傳輸，並在接收端透過 JSON.parse() 解析。
外部返回：在收到 save-draft 回調前，父頁面不應直接關閉、跳轉或銷毀當前 iframe 頁面。儲存失敗的典型場景包括但不限於網路或請求逾時、登入態失效、伺服器端異常、當前頁面資料不滿足儲存條件。
權限規則：本期不新增額外權限判斷，沿用影片創作頁面當前已有的草稿儲存權限與登入態規則。

如有任何疑問或需要進一步的技術支援，請聯繫我們的技術支援團隊。

**Polyv 影片創作頁面嵌入與通訊協定**