Polyv Video Creation Page Embedding and Communication Protocol

Updated: 2026-06-16 17:42:09

Document Version: v1.1
Last Updated: June 16, 2026

1. Overview

This document aims to help developers seamlessly integrate Polyv's AI video creation functionality into third-party business platforms in the form of iframe. By following the guidelines in this document, you can achieve:

Interface Customization: Control the visibility of specific buttons on the embedded page via URL parameters.
Function Invocation: Use the Window.postMessage API to establish secure communication between your parent page and Polyv's iframe page, programmatically triggering operations such as video generation and draft saving.

This document is intended for customers who need to provide AI video creation capabilities within their own products and wish to customize the integration interface and workflow.

2. Quick Start

To achieve basic embedding and communication, you need the following two steps:

Embed the iframe: Place the iframe of the Polyv AI video creation page within your page.
Implement the Communication Script: Write JavaScript code to listen for the iframe's ready state and send commands.

Below is a basic HTML structure example:

<!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. Feature Details

3.1. Interface Customization (URL Parameters)

You can customize the appearance of the embedded page by appending specific parameters to the src attribute link of the iframe. This method is flexible and easy to implement.

Parameter List

Parameter	Type	Description	Example
`video-production-submit`	String	`N`: Hides the [Generate Video] button in the top right corner.	`...create?video-production-submit=N`
`video-production-return`	String	`N`: Hides the [Back] button in the top left corner.	`...create?video-production-return=N`

Combined Usage Example

To hide both the "Generate Video" and "Back" buttons, configure the src as follows:

<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. Interactive Communication (PostMessage API)

To achieve precise control over operations within the iframe from the parent page, we have defined a bidirectional communication protocol based on postMessage.

Core Flow:

After the iframe page loads, it sends a ready status notification to the parent page.
Upon receiving the ready notification, the parent page confirms that the iframe is ready.
Subsequently, the parent page can send specific commands like create and save-draft to the iframe.
After the iframe successfully submits a generation task, it sends a submit-success event notification to the parent page.
When the integrating party hides the iframe's built-in [Back] button and uses its own [Back] button, the parent page should first send save-draft to the iframe, wait for the iframe to return the draft saving result, and then execute its own back logic.

JavaScript Communication Logic Implementation

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. Communication Protocol Specification

All communication messages are in JSON string format, and the type is fixed as ai-video-production. In the draft saving protocol, both the parent page's request and the iframe's response use the save-draft event; the parent page's request does not carry success, while the iframe's response carries success and message.

4.1. Iframe → Parent Page

`event` Value	Description	Payload Example
`ready`	Notifies the parent page that the iframe has finished loading and is ready to receive commands. This is a critical "handshake" signal.	`{"type": "ai-video-production", "event": "ready"}`
`submit-success`	Notifies the parent page that the video generation task has been successfully submitted to the backend processing queue. Indicates the user's request has been accepted.	`{"type": "ai-video-production", "event": "submit-success"}`
`save-draft`	Notifies the parent page that the result of the current draft save has been returned. The parent page can decide whether to proceed with its own back logic based on `success`.	`{"type": "ai-video-production", "event": "save-draft", "success": true

4.2. Parent Page → Iframe

`event` Value	Description	Payload Example
`create`	Requests the iframe to start the video generation process. Its effect is equivalent to clicking the [Generate Video] button inside the iframe.	`{"type": "ai-video-production", "event": "create"}`
`save-draft`	Requests the iframe to save a draft of the current editing content. This action is typically triggered by the integrating party's own [Back] button.	`{"type": "ai-video-production", "event": "save-draft"}`

4.3. Draft Saving and External Back Flow

When the integrating party hides the [Back] button in the top left corner of the iframe page using video-production-return=N and uses its own [Back] button on the parent page, the following flow should be followed:

The user clicks the integrating party's own [Back] button.
After the parent page confirms receipt of the iframe's ready event, it sends save-draft to the iframe.
The iframe saves a draft of the current editing content.
The iframe calls back save-draft to the parent page, expressing the save result via success.
When success is true, the parent page can proceed with its own back logic.
When success is false, the parent page should not automatically navigate back; it is recommended to prompt the user or log the error based on message.

If there are no new unsaved changes on the current page, the iframe should still call back save-draft and return success: true. The parent page does not need to additionally determine whether there are unsaved changes.

5. Important Notes

Security Policy: In addEventListener, strictly validate event.origin to ensure the message source is https://console.polyv.net. When using postMessage, explicitly specify targetOrigin and avoid using * to prevent sensitive data leakage.
Loading Timing: The parent page must wait and confirm receipt of the iframe's ready event before sending business commands (e.g., create, save-draft). It is recommended to disable the parent page's control buttons until the ready signal is received.
Message Format: All communication data must be serialized into a string via JSON.stringify() for transmission and parsed via JSON.parse() on the receiving end.
External Back: The parent page should not directly close, navigate away from, or destroy the current iframe page before receiving the save-draft callback. Typical scenarios for save failure include, but are not limited to, network or request timeout, invalid login session, server-side errors, or current page data not meeting save conditions.
Permission Rules: No additional permission checks are added in this version. The existing draft saving permissions and login session rules of the video creation page will be used.

If you have any questions or require further technical support, please contact our technical support team.

Live Streaming Products

**Polyv Video Creation Page Embedding and Communication Protocol**