下面的原始 HTTP 只能运行在商户后端。ID 与 Key 都应来自已授权的业务流程；origin 必须与实际 H5 来源一致，并由后端可信配置核实。

POST /api/v1/recording-tokens
Authorization: Bearer <完整项目服务端凭证>
Content-Type: application/json

{
  "origin": "https://h5.customer.example",
  "flowRef": "flow-your-business-000001",
  "idempotencyKey": "entry-your-business-000001"
}

同 Key 换参数返回 IDEMPOTENCY_CONFLICT。重试复用原 Key；每凭证 5 分钟最多申请 300 次，429 按 Retry-After 退避。

只补续期请直接看第 05 节，不用重做已完成的流程。/business/recording-context 和 /business/recording-token 是商户自建接口的示例路径，不是平台接口，可替换为已有受业务身份/CSRF保护的接口。context 返回原会话 ID（首次为 null）和商户自己的 CSRF 值。

<script src="https://khs.szshuqi.com/sdk/recorder.min.js"
        crossorigin="anonymous" defer></script>
<script>
window.addEventListener("DOMContentLoaded", async () => {
  const status = document.querySelector("#recording-status");
  const showStatus = message => { if (status) status.textContent = message; };
  KHSRecorder.error(error => {
    showStatus(`${error.code}: ${error.message}；请求编号 ${error.requestId || "本地检查"}`);
  });

  try {
    const response = await fetch("/business/recording-context", {
      credentials: "same-origin", cache: "no-store"
    });
    const context = await response.json();
    if (!response.ok || context.ok !== true) throw new Error("无法读取当前业务录制");

    const tokenProvider = async ({ reason, traceSessionId, origin, handoffToken, signal }) => {
      const result = await fetch("/business/recording-token", {
        method: "POST", credentials: "same-origin",
        headers: { "Content-Type": "application/json", "X-CSRF-Token": context.csrf },
        body: JSON.stringify({ reason, traceSessionId, origin, handoffToken }),
        signal
      });
      const data = await result.json();
      if (!result.ok || data.ok !== true) throw Object.assign(new Error(data.message || "录制凭证请求失败"), {
        code: data.code, requestId: data.requestId, retryAfter: data.retryAfter
      });
      return data;
    };

    await KHSRecorder.init({
      endpoint: "https://khs.szshuqi.com",
      tokenProvider,
      ...(context.traceSessionId ? { traceSessionId: context.traceSessionId } : {}),
      pagehideStrategy: "flush"
    });
    showStatus("录制已开始");
  } catch (error) {
    showStatus(error.message || "录制启动未完成，请稍后重试");
  }
});
</script>
<p id="recording-status" role="status" aria-live="polite"></p>

动态 SDK 最多缓存 60 秒。回调参数由 SDK 自动提供；signal 传给 fetch，不放进 JSON。原会话 ID 在首屏 init 前传入，恢复还须满足第 05 节的条件。

以下参数由 SDK 自动提供；续期仅用 traceSessionId 拼接平台请求路径，其余不是平台续期接口必填参数。

示例里的 context.csrf 来自商户自己的防跨站请求机制，不由平台签发；沿用现有业务身份和 CSRF 保护即可。

刷新续传须在离页前配置 pagehideStrategy:"flush"（默认 finish），业务结束才 stop。恢复还需原会话仍可恢复、Token 与当前页面来源匹配、本地缓存可用；仅传原 ID 不保证待传数据完整恢复。默认中断恢复窗口为 24 小时，是否可恢复以平台响应为准。

源页用 KHSRecorder.handoff(nextUrl, createHandoff) 等待当前片段完成后再跳转。createHandoff 调商户受保护后端，再由后端调用 /api/v1/sessions/{sessionId}/handoffs。目标页 Provider 的 handoff 分支调用 /api/v1/handoffs/redeem；initial 签发，resume/过期等续原 ID。

接续凭证有效期 5 分钟，只对指定项目和目标来源有效；重复兑换复用子会话。新片段以 journeyId/parentSessionId 关联，单独计额度、绑定订单并执行自身 72 小时确认策略。Token 不能直接跨域复用；后端仍须校验跳转和业务归属。hash 路由需测试 khs_handoff fragment 兼容性。

window.addEventListener("khs:finished", event => {
  const { evidenceStatus } = event.detail;
  const labels = {
    ready: "平台已返回正式存证完成，请由后端核对最终结果",
    awaiting_confirmation: "录制已上传，等待商户确认保存",
    archiving: "录制已上传，平台正在转存",
    debug_complete: "调试录制已封存，仅本地临时保存",
    unknown: "录制已上传，请查询最终保存状态"
  };
  showStatus(labels[evidenceStatus] || labels.unknown);
});
async function finishBeforeNavigation(nextUrl) {
  try {
    await KHSRecorder.stop();
    // 是否还要等待正式存证，由业务后端的完成要求决定。
    location.assign(nextUrl);
  } catch (error) {
    const current = KHSRecorder.getStatus();
    showStatus(`尚有 ${current.pendingChunks} 个分块待传，请恢复网络后重试`);
    throw error;
  }
}

返回值还包含 recordingComplete:true 和 persistenceState，getStatus 暴露 serverStatus。ready 需要正式环境、permanent、已就绪状态和 Manifest；旧 khs:sealed 仅为兼容别名，标记 canonicalEvent:khs:finished，不要双重监听执行业务。

// Node 官方客户端；rawBody 是尚未经过 JSON 解析的原始正文
const { handleWebhook } = require("./sdk"); // 下载包内的正式服务端组件
await handleWebhook(
  rawBody,
  signatureHeader, // X-KHS-Signature
  process.env.KHS_WEBHOOK_SECRET,
  async (eventId, event) => {
    // 商户必须实现：数据库唯一事件ID + 业务操作在同一事务
    // 已处理事件幂等成功；处理失败回滚并抛错
    return businessInbox.processOnce(eventId, event);
  }
);
// 业务已落库或可靠入队后，HTTP才返回2xx；失败返回非2xx。

verifyWebhook 返回已验签事件；handleWebhook 只负责验签并调用 processOnce，不内置业务数据库。businessInbox 是商户必须实现的事务适配器，不能用内存 Set 代替；重复已处理事件直接成功。Express 原始正文路由要放在 express.json() 前。

// SDK 已加载后、init()/resume() 之前注册
const cancelError = KHSRecorder.error(error => {
  showStatus(`${error.code}: ${error.message}；请求编号 ${error.requestId || "本地检查"}`);
  // 如需上报，仅选取必要字段，不能打印完整 Token 响应
  reportSafeError({
    code: error.code, requestId: error.requestId,
    stage: error.stage, status: error.status
  });
});

// 仅联调时按需查看诊断
const cancelDebug = KHSRecorder.debug(info => showDiagnostics(info));
const diagnostics = KHSRecorder.getDiagnostics();
// SPA组件销毁时：cancelError(); cancelDebug();

showStatus/reportSafeError/showDiagnostics 是商户自己的 UI/日志接线函数。KHSRecorder.error 不会代替 Promise 错误处理，init/stop 仍须 try/catch；getDiagnostics 用于安全诊断，不意味着录制输入已脱敏。