专业版接入 ​

接入方服务端通过 /api/grant/otp_code 获取一次性 code，前端加载专用 SDK、创建 iframe 并监听初始化结果。首次联调处理 APP_READY 和 APP_ERROR 即可，页面成功打开后再逐项增加生成、停止和导出事件。

SDK 初始化示例 ​

如果需要先了解授权链路，请阅读 专业版鉴权；如果需要先了解完整业务链路，请阅读 业务流程图。

最小 HTML 示例 ​

专业版使用独立 SDK 文件：

html
<script src="https://api-static.aippt.cn/aippt-coding.js"></script>

下面是一个可以直接保存为 index.html 的最小页面。接入方服务端先按 专业版鉴权 获取一次性 code，再把 APP_KEY、AUTH_CODE 和可选 CHANNEL 替换为真实值。

html
<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>专业版最小接入示例</title>
    <style>
      html,
      body {
        width: 100%;
        height: 100%;
        margin: 0;
      }

      #slide-root {
        width: 100vw;
        height: 100vh;
      }

      #status {
        position: fixed;
        top: 12px;
        left: 12px;
        z-index: 10;
        padding: 6px 10px;
        border-radius: 4px;
        background: rgba(17, 24, 39, 0.82);
        color: #fff;
        font-size: 13px;
      }
    </style>
  </head>
  <body>
    <div id="status">正在加载专业版...</div>
    <div id="slide-root"></div>

    <script src="https://api-static.aippt.cn/aippt-coding.js"></script>
    <script>
      // 由接入方服务端获取，不要在前端保存或计算 Secret Key。
      const APP_KEY = 'your-appkey'
      const AUTH_CODE = 'auth-code'
      const CHANNEL = ''

      const statusEl = document.getElementById('status')
      const setStatus = (text) => {
        statusEl.textContent = text
      }

      async function bootstrap() {
        try {
          const ppt = await AipptAgent.create({
            auth: {
              appKey: APP_KEY,
              code: AUTH_CODE,
              channel: CHANNEL
            },
            mount: {
              container: document.getElementById('slide-root')
            },
            iframe: {
              parentOrigin: window.location.origin
            },
            events: {
              onReady(event) {
                setStatus('专业版已就绪')
                console.log('APP_READY', event)
              },
              onEvent(event) {
                console.log('专业版 event', event.type, event.payload)
              },
              onError(error) {
                setStatus('专业版初始化失败')
                console.error('专业版 error', error)
              }
            }
          })

          window.agent = ppt
        } catch (error) {
          setStatus('专业版初始化失败')
          console.error('AipptAgent.create failed', error)
        }
      }

      bootstrap()
    </script>
  </body>
</html>

code 是 5 分钟、单次有效的一次性凭证，只用于 AipptAgent.create 初始化。收到 APP_READY 表示初始化成功；收到 APP_ERROR 表示初始化失败，随后 Promise reject。

aippt-coding.js 只用于新版专业版；预装版 UI 仍使用 aippt-iframe-sdk.js。两者是独立文件，请不要混用。

基础事件处理 ​

事件建议处理
APP_READY隐藏加载态，允许用户操作；可读取 auth.tokenExpiresAt 和 auth.refreshRequiredAt 安排重新获取 code。
APP_ERROR展示初始化失败提示。
GENERATE_COMPLETE记录生成结果或刷新业务状态。
GENERATE_STOPPED展示生成已停止，并区分用户手动停止或外部停止。
PPT_EXPORT_COMPLETE需要同步导出结果或接管下载时展示下载入口。

完成以上步骤后，即可得到一个可用的基础接入页面。

建议

基础接入优先只处理 APP_READY、APP_ERROR、GENERATE_COMPLETE 和 GENERATE_STOPPED。如果需要同步导出结果或接管下载，再补充 PPT_EXPORT_COMPLETE。

按业务目标增加配置 ​

使用方式配置方式说明
直接进入生成页面默认无需配置；或设置 routerOptions.list默认进入 /generate 新建任务态。
恢复生成会话设置 routerOptions.generate.sessionId仍在同一个 Generate 页面展示会话态。
直接进入编辑器设置 routerOptions.editor.sessionIdEditor 可附带 0-based pageIndex。
只开放一个模块设置 routerOptions.list = ['generate'] 或 ['editor']不传 list 默认全选；仅 Editor 时必须同时提供 editor.sessionId。
接管下载流程设置 features.downloadMode = 'external'适合接入方已有下载中心、文件记录或审计流程。
控制页面功能入口设置 features.featureCodes适合按业务场景控制高级编辑、放映、导出等按钮。
控制 Generate Skills设置 features.showSkills控制 Generate 新建任务态是否展示 Skills 区域。
宿主主动生成调用 ppt.startGeneration({ content })适合宿主已有主题输入框或自动化生成流程。

与旧 UI 自定义创建的区别

专业版不继续兼容旧 UI 的 custom_generate.type / custom_generate.taskId 多类型协议。宿主主动生成请使用 initial.generate.content 或 ppt.startGeneration()。

宿主页面必须覆盖的状态 ​

状态建议表现
加载中在 iframe 容器区域展示 loading 或 skeleton。
初始化失败展示可理解的错误提示，并保留重试或返回入口。
生成中展示生成进度，不建议让页面处于无反馈状态。
导出中展示导出中状态，避免用户重复点击。
导出失败展示失败原因或重试入口。