专业版事件推送 ​

事件推送由宿主发给 iframe，用于切换路由、开始生成、导出、放映、停止生成或刷新认证。执行结果仍通过 事件通知 返回。

类型方向用途
事件通知专业版通知接入方页面接收初始化、生成、保存、导出和停止结果
事件推送接入方页面通知专业版主动要求 iframe 执行动作

如果只是接收 iframe 内行为结果，请使用 事件通知。只有接入方需要主动控制 iframe 行为时，才需要使用事件推送。

可发送的七类动作 ​

当前开放 NAVIGATE、OPEN_SESSION、START_GENERATION、EXPORT、START_PRESENTATION、STOP_GENERATION 和 AUTH_REFRESH_REQUEST。

调用前检查 ​

推送调用前确认结果事件
NAVIGATEroute 只能为 generate、editor；Editor 必须有 sessionIdROUTE_CHANGED / COMMAND_ERROR
OPEN_SESSIONGenerate 已包含在 routerOptions.list，并提供非空 sessionIdROUTE_CHANGED / COMMAND_ERROR
START_GENERATION提供非空 generate.content，当前无冲突生成任务GENERATE_START / COMMAND_ERROR
EXPORT当前已进入 Editor，且导出能力可用PPT_EXPORT_* / COMMAND_ERROR
START_PRESENTATION当前已进入 Editor，且放映能力可用PRESENTATION_STARTED / COMMAND_ERROR
STOP_GENERATIONiframe 已初始化成功，且当前确实存在进行中的生成任务GENERATE_STOPPED
AUTH_REFRESH_REQUEST已收到 AUTH_REFRESH_REQUIRED，并由接入方服务端重新申请到新的 /api/grant/otp_code codeAUTH_REFRESH_SUCCESS / AUTH_REFRESH_FAILED

事件推送只负责把宿主页面的控制动作发送给 iframe。接入方仍应通过 事件通知 处理最终状态，不要仅凭 SDK 方法调用成功就更新业务结果。

STOP_GENERATION 用于接入方从外部停止正在进行的生成任务。

ts
ppt.stopGeneration()

STOP_GENERATION 当前不要求传入业务字段。接入方如需在自己的页面中记录停止来源，可在外层业务状态中保存；iframe 返回给接入方的停止结果以 GENERATE_STOPPED 为准。

使用建议

停止动作更适合由宿主页面中的“取消任务”“停止生成”等明确按钮触发，不建议在无用户感知的情况下静默中断正在进行的生成流程。

刷新认证 ​

访问凭证有效期以 APP_READY.auth.tokenExpiresAt、APP_READY.auth.tokenExpiresIn 和 APP_READY.auth.refreshRequiredAt 为准。接入方不要写死固定时长，可以选择两种方式处理过期：

方式行为
自主刷新接入方根据 APP_READY.auth.refreshRequiredAt 自己重新申请 code，销毁并重新创建 iframe。
页面内刷新iframe 发送 AUTH_REFRESH_REQUIRED，接入方重新获取新的 code 后，通过 ppt.refreshAuth() 发送 AUTH_REFRESH_REQUEST，iframe 使用新凭证更新认证状态，不重建页面。

页面内刷新示例（SDK 会发送 AUTH_REFRESH_REQUEST）：

ts
const ppt = await AipptAgent.create({
  auth: {
    appKey: 'your-appkey',
    code: 'auth-code'
  },
  events: {
    async onEvent(event) {
      if (event.type !== 'AUTH_REFRESH_REQUIRED') return
      const freshCode = await fetchFreshCode()
      await ppt.refreshAuth({ code: freshCode })
    }
  }
})

iframe 收到并应用成功后，会发送 AUTH_REFRESH_SUCCESS；新 code 缺失、复用旧 code 或凭证刷新失败时发送 AUTH_REFRESH_FAILED。

推送列表 ​

停止结果 ​

推送 STOP_GENERATION 后，专业版会通过 GENERATE_STOPPED 通知接入方生成已停止。

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

GENERATE_STOPPED 的 source 用于区分停止来源：

source含义
user用户在专业版内手动停止
host接入方通过事件推送停止
backend服务端流程取消或中断

推送能力边界 ​

  • 事件推送不是初始化配置，不替代 AipptAgent.create 参数。
  • NAVIGATE 不接受 /、/generate、/editor、/speaker 等内部 path，只接受语义模块名 generate、editor。
  • START_PRESENTATION 的 fullscreen 受浏览器用户手势限制；无法执行时返回 COMMAND_ERROR/USER_GESTURE_REQUIRED。
  • requestId 会在路由、放映、导出或错误结果中尽量原样返回，便于宿主关联异步操作。
  • STOP_GENERATION 只用于停止正在进行的生成任务。
  • AUTH_REFRESH_REQUEST 只用于刷新 iframe 页面认证状态，不替代初始化配置。
  • AUTH_REFRESH_REQUEST 只传 status: true 和新 code；不要在事件里传 token 或其他认证字段。
  • AUTH_REFRESH_REQUEST 不能复用初始化时已消费的 code。
  • STOP_GENERATION 的停止动作由事件类型触发，data 不是必填参数。
  • 额度、权限和服务可用性属于平台侧校验结果，不通过前端事件推送完成。
  • 推送后的结果以 事件通知 中的 GENERATE_STOPPED 为准。