专业版事件通知

iframe 用事件把初始化、生成、保存和导出状态同步给宿主。接入方应按业务阶段管理页面状态，不要为每个事件建立互不关联的处理分支。

事件传递机制

专业版通过 iframe SDK 向接入方页面发送事件。这些事件用于同步页面状态、记录生成结果、处理下载流程和展示异常提示。

iframe 内部仍使用 { type, data: JSON.stringify(payload) } 消息格式。标准 SDK 会将其包装成 { type, payload, timestamp, source } 后通过 events.onEvent(event) 传给接入方。

如果需要由接入方主动通知 iframe 执行动作，请阅读 事件推送。

查看最小监听示例

AipptAgent.create({
  auth: {
    appKey: 'your-appkey',
    code: 'auth-code'
  },
  events: {
    onEvent(event) {
      if (event.type === 'GENERATE_COMPLETE') {
        console.log(event.payload)
      }
    }
  }
})

回调参数结构

参数 / 场景	读法	示例
type	事件名，决定走哪条业务分支。	GENERATE_COMPLETE 表示生成成功。
payload	当前事件携带的业务字段。	payload.workId、payload.sessionId
用 SDK 的 events.onEvent	event.type 是事件名，event.payload 是已解析后的对象	event.payload.workId、event.payload.sessionId
直接监听 postMessage	外层消息里 type 是事件名，data 是 JSON 字符串	需要先 JSON.parse(event.data.data)
字段为空或不存在	表示当前事件或当前阶段没有这个业务信息	PPT_EXPORT_ERROR 可能没有 url

通信与安全

项	要点
iframe -> 宿主	事件通知、状态回传、结果回执，入口是 events.onEvent(event)。
宿主 -> iframe	主动控制、刷新认证、停止生成，详见 事件推送。
安全要求	校验 origin，发送时使用明确的 targetOrigin；payload 只传 JSON 可序列化数据，不传 token。

基础事件流程

基础接入需要覆盖以下 4 个宿主页面状态；字段、枚举和完整事件清单可作为后续查询资料。

01判断 iframe 是否可用

监听 APP_READY 和 APP_ERROR，控制初始化 loading 和失败提示。

02处理生成结果

用 GENERATE_COMPLETE 判断生成成功，用 GENERATE_STOPPED 区分停止原因。

03展示过程进度

需要进度条时再监听 GENERATE_PROGRESS，注意 completed 不是最终成功依据。

04接管导出下载

features.downloadMode = 'external' 时监听 PPT_EXPORT_COMPLETE，由宿主页面展示下载入口。

高频事件

事件	什么时候看	重点字段
APP_READY	iframe 初始化成功，可以解除宿主页面 loading。	route、pageIndex、sessionId、auth.*
APP_ERROR	初始化或运行异常，需要展示失败提示并记录错误。	code、message、statusCode
ROUTE_CHANGED	宿主运行时路由切换或主动生成导致的路由变化完成。	route、sessionId、pageIndex、requestId
COMMAND_ERROR	宿主主动指令无法执行。	command、code、message、requestId
GENERATE_PROGRESS	展示生成过程进度，只用于阶段和页码。	status、phase、pageIndex
GENERATE_COMPLETE	生成成功的最终依据，适合写入业务记录。	workId、sessionId、totalPages
GENERATE_STOPPED	生成停止，不等同于生成失败。	source、reason、message
PPT_EXPORT_COMPLETE	导出完成，可展示下载入口或写入文件记录。	format、filename、url
PRESENTATION_STARTED	宿主主动放映成功。	mode、pageIndex、sessionId、workId、requestId

最小监听

通用接入至少监听 APP_READY、APP_ERROR、GENERATE_COMPLETE、GENERATE_STOPPED。保存、导出、认证刷新可按业务需要继续补充。

事件先后关系

页面初始化

AipptAgent.create -> APP_READY
AipptAgent.create -> APP_ERROR

页面初始化成功时会收到 APP_READY，失败时会收到 APP_ERROR。宿主页面可以据此解除 loading 或展示初始化失败提示。

生成流程

开启 features.generateApproval：
GENERATE_START_REQUEST -> GENERATE_START_RESPONSE(approved=true) -> GENERATE_START
GENERATE_START_REQUEST -> GENERATE_START_RESPONSE(approved=false) -> 保留输入，不开始生成

GENERATE_START -> GENERATE_PROGRESS -> GENERATE_COMPLETE
GENERATE_START -> GENERATE_PROGRESS -> GENERATE_ERROR
GENERATE_START -> GENERATE_STOPPED
用户提交 -> GENERATE_ERROR（任务创建阶段失败，可能尚未发送 GENERATE_START）

接入方可基于这一时序维护“生成中 / 生成成功 / 生成失败 / 已停止”四类状态。

GENERATE_START_REQUEST 只在 iframe 内用户按回车或点击发送时触发；宿主调用 startGeneration() 不会再次请求确认。请求 payload 包含 requestId、可选 sessionId、entry=home|chat|skill 和 trigger=enter|click，不包含提示词、附件、token 或初始化参数。等待宿主响应期间不会创建会话或调用生成接口，也没有业务超时；宿主通过 respondToGenerateRequest() 返回同一个 requestId。

父 SDK 在生产环境通过内部 Tracker 上报 SDK_GENERATE_APPROVAL，结果包括 requested、approved、rejected、cancelled、ignored。排查时可用 SDK_GENERATE_APPROVAL.data.requestId 关联后续 GENERATE_START.payload.approvalRequestId；同时记录 entry、trigger、elapsedMs、reasonCode 和 route。埋点不包含 prompt、附件、token、客户拒绝文案、完整 INIT 参数或服务端原始响应，埋点异常不会阻断审批与生成。

任务创建阶段也可能直接返回 GENERATE_ERROR。例如输入内容未通过安全检查时，iframe 会先使用后端 message 提示终端用户，同时向宿主发送以下错误信息：

{
  "message": "输入的文本可能存在违规内容，请重新修改后尝试",
  "code": "CONTENT_RISK",
  "reason": "CONTENT_RISK",
  "statusCode": 400,
  "msgKey": "api.content_risk",
  "msgParams": {},
  "requestId": "request-id",
  "sessionId": "session-id"
}

该场景表示任务未创建成功，因此宿主不应等待 GENERATE_STOPPED。建议使用 code 做错误分流，优先向用户展示 message；接入方有自己的多语言体系时，可使用 msgKey 和 msgParams 映射文案。requestId、sessionId 可能为空，仅用于已有值时辅助排障。

GENERATE_COMPLETE 是后端任务正常完成的唯一信号。接入方应以本事件作为“生成成功”判断依据，不要用 GENERATE_PROGRESS.status === 'completed' 或 UI 状态推断。

生成完成判定细节

触发链路：后端 SSE 推送 completed 事件 -> iframe 内 handleCompleted -> 调用 sendGenerateComplete。

场景	结果	说明
正常生成完成（SSE completed 带 work_id）	触发	workId 取 SSE 的 work_id
正常生成完成（SSE completed 不带 work_id，但 store 里已有 workId）	触发	workId 回退到 store 已有值
SSE completed 既无 work_id 且 store 无 workId 且非 replay	不触发	走 handleCompletedWithoutWork 分支，iframe 不向宿主发送 GENERATE_COMPLETE。
replay 历史消息（isReplaying=true）	触发	即使无 work_id 也会发送，用于历史会话恢复。
生成失败	不触发	走 GENERATE_ERROR。
用户主动停止 / 接入方外部停止 / 后端中断	不触发	走 GENERATE_STOPPED。
余额不足、账务类错误	不触发	后端会以 stopped 形式结束，前端表现为 GENERATE_STOPPED。

GENERATE_COMPLETE 字段含义

字段	来源	含义
workId	SSE work_id 或 store 已有值	作品 ID
totalPages	iframe store 已渲染的 pages.length	前端实际收到的页数
totalCount	SSE total_count	后端声称的总页数；正常完成时应与 totalPages 相等
sessionId	iframe session store	当前会话 ID
title	iframe session store 的 navTitle	会话标题

边界情况

若接入方收到 SSE 完成但没有收到 GENERATE_COMPLETE，大概率命中了“既无 work_id 又无 store workId 且非 replay”分支。通常意味着后端 completed 事件缺少 work_id，需要后端排查，而非接入方逻辑问题。

保存与导出

PPT_EXPORT_START -> PPT_EXPORT_COMPLETE
PPT_EXPORT_START -> PPT_EXPORT_ERROR

当 features.downloadMode = 'external' 时，接入方通常需要基于上述事件自行完成下载反馈。

场景处理

接入方可按业务场景处理事件；需要确认字段含义或枚举值时，可查看后面的参考资料。

接入方要做的事	主要监听	优先读取字段	处理建议
判断 iframe 是否可用	APP_READY / APP_ERROR	version、sessionId、code、message、statusCode	成功后解除页面 loading；失败时展示初始化失败，并记录错误码。
同步宿主导航状态	ROUTE_CHANGED / COMMAND_ERROR	route、sessionId、pageIndex、requestId、code	只使用 generate/editor 公开模块，不根据 iframe 内部 URL 猜测业务状态。
确认用户是否可以开始生成	GENERATE_START_REQUEST	requestId、sessionId、entry、trigger	客户前端完成本地权限判断后调用 respondToGenerateRequest()；必须显式批准或拒绝。
展示生成进度	GENERATE_START / GENERATE_PROGRESS	sessionId、phase、pageIndex、totalPages、message	非页级阶段不要渲染真实页码，只展示阶段文案。
记录生成成功结果	GENERATE_COMPLETE	workId、sessionId、title、totalPages、totalCount	以本事件作为生成成功依据，并把 workId 绑定到接入方业务记录。
区分生成失败或停止	GENERATE_ERROR / GENERATE_STOPPED	code、message、source、reason、workId、msgKey、msgParams、requestId	失败走错误提示；CONTENT_RISK 表示输入内容需要修改且任务未创建，不等待停止事件；其他停止场景根据 source 和 reason 给出不同文案。
处理编辑器保存	PPT_SAVE_*	id、filename、saveMode、status、errorCode、recoveryAction	自动保存可弱提示；手动保存失败或冲突需要给用户恢复动作。
展示导出或下载入口	PPT_EXPORT_COMPLETE / PPT_DOWNLOAD_START	format、filename、fileSize、url、workId、sessionId	features.downloadMode = 'external' 时由宿主页面接管下载按钮和下载记录。
刷新认证	AUTH_REFRESH_REQUIRED / AUTH_REFRESH_*	reason、auth.tokenExpiresIn、message、errorCode	收到刷新请求后重新获取 fresh code，再调用 ppt.refreshAuth({ code })。

事件与字段索引

字段、枚举和完整事件清单已拆到独立 reference 页。主流程接入时不需要先读完这些表。

想查什么	页面
宿主主动停止生成或刷新认证	事件推送
字段含义、专属字段、枚举值	事件字段说明
24 个事件的完整 type 和 data payload	完整事件清单

容易判断错的事件

展开高频误用清单

不要这样做	正确做法
用 GENERATE_PROGRESS.status === 'completed' 判断生成成功。	以 GENERATE_COMPLETE 作为宿主侧生成成功依据。
把 pageIndex = -1 当真实页码展示。	先看 phase；non-page 阶段只展示阶段文案。
把所有 code 都当成鉴权凭证。	父→子 AUTH_REFRESH_REQUEST.code 是 fresh code；APP_ERROR.code / GENERATE_ERROR.code 是错误码。
复用初始化时已经消费过的 code 刷新认证。	重新向服务端申请 fresh code，再通过 ppt.refreshAuth() 推给 iframe。
假设所有事件都会返回 workId、url 或 sessionId。	按事件类型处理可选字段，不存在时走兜底逻辑。
把 APP_READY 理解成所有业务能力都完成。	APP_READY 只表示初始化、鉴权和服务开关校验通过。
在事件 payload 中传递或读取 token。	事件 payload 不包含 token；认证刷新只通过 fresh code 完成。
监听 BILLING_UNAVAILABLE 判断额度异常。	该名称当前只是 SDK 预留常量，iframe 不发送；生成中额度异常读取 GENERATE_ERROR.code/reason，初始化服务不可用读取 APP_ERROR。

用结果验证事件接入

场景	验收重点
初始化	成功时稳定收到 APP_READY；失败时收到 APP_ERROR 并能展示失败提示。
生成	成功、失败、停止三条路径都能驱动宿主页面状态；生成成功以 GENERATE_COMPLETE 为准。
导出下载	features.downloadMode = 'external' 时监听 PPT_EXPORT_START、PPT_EXPORT_COMPLETE、PPT_EXPORT_ERROR，由宿主页面展示下载入口。
业务记录	sessionId、workId、导出文件信息能被接入方正确记录。

当前开放事件范围以以上列表为准。接入方应仅基于已列出的事件类型和字段完成状态同步与页面联动。