嵌入 Theo Browser

​

快速開始

1. 在你的後端創建會話（切勿將 THEO_API_KEY 暴露給瀏覽器）：

import { Theo } from "@hitheo/sdk";
const theo = new Theo({ apiKey: process.env.THEO_API_KEY! });

const session = await theo.browser.create({
  url: "https://example.com",
  region: "us-west-2",
});
return Response.json({ embed_url: session.embed_url });

2. 將該 URL 放入前端的 iframe 中：

<iframe
  src="{embed_url}"
  width="100%"
  height="600"
  allow="clipboard-read; clipboard-write"
  sandbox="allow-scripts allow-same-origin"
></iframe>

• 首次渲染時獲取正確的實時視圖 URL（不會出現 about:blank 閃屏）
• 監聽 browserbase-disconnected 的 postMessage 消息
• 在 CDP 目標發生變化時自動重新獲取併為 iframe 重新賦 key
• 斷開連接時以 10 秒為間隔緊密輪詢，連接正常時放寬為 30 秒
• 帶有 Theo 品牌的地址欄 + 實時狀態指示器 + 重連遮罩層

​

令牌的工作原理

• 格式： {APP_ORIGIN}/embed/browser/{sessionId}?token=<hmac>
• 作用範圍： 該令牌與特定會話以及創建該會話的用戶綁定
• 有效期： 60 分鐘（Theo Browser 會話硬性上限為 20 分鐘，因此這為 keep_alive 會話留出了餘量）
• 密鑰： 由服務器端使用 BROWSER_EMBED_TOKEN_SECRET 簽名，永不暴露給客戶端
• 輪換： 每次調用 GET /api/v1/browser/sessions/:id 都會生成一個新令牌，因此長時間運行的儀表盤可以按需刷新 iframe

​

斷線處理

// Listen on the parent window for the iframe's disconnect event.
window.addEventListener("message", (ev) => {
  if (ev.data === "browserbase-disconnected") {
    // Option A: let Theo handle it — refetch /live?force=1 and rekey.
    // Option B: surface a "reconnecting…" UI to your user.
  }
});

​

安全姿態

• Iframe 沙箱： allow-scripts allow-same-origin 是保持 DevTools 前端與 CDP WebSocket 存活所需的最小權限集合。添加 allow-forms / allow-popups 沒有任何功能上的好處，反而可能觸發意外的導航，把 iframe 帶離實時視圖。
• frame-ancestors *： 嵌入頁面設置了 Content-Security-Policy: frame-ancestors *，因此任何來源都可以將其加載到 iframe 中。如果你想限制哪些來源可以加載該嵌入頁面，請在你自己的 CDN 層終止該 iframe 請求並應用你自己的響應頭。
• iframe 中不含任何憑據： 嵌入頁面永遠不會接觸到你的 API 密鑰。它通過一個使用令牌鑑權的配套路由 /embed/browser/:id/live 進行通信。

​

結束會話

await theo.browser.end(session.session_id);

​

相關內容

• Browser Sessions API —— 完整的 /api/v1/browser/sessions 接口
• Theo Browser SDK —— 適用於 Node/Deno/edge 的類型化輔助工具