@ dodomain/ 连接
可嵌入的浏览器部件 域名打开主机连接流
在一个模式的 Iframe 中将其生命周期事件转发回您的应用程序。 与
@dodomain/node,在服务器上会话符号的薄荷.
📖 附有可操作示例的指南 : dodomain.io/docs/widget (英语)
· 所有文件: dodomain.io/docs (英语)使用反应? @dodomain/react 用钩子包裹此部件.
安装
npm install @dodomain/connect
# or: pnpm add @dodomain/connect · yarn add @dodomain/connect
零运行时间依赖, ~3KB 浏览器捆绑( 双端无害环境管理+ CJS + 自定义) .d.ts; 数据
捆绑留下 无分区 看到了吗 test/build.smoke.test.ts) (中文(简体) ).
使用量
import { showDoDomain } from "@dodomain/connect";
// token comes from your server: POST /api/v1/sessions via @dodomain/node
const { token } = await fetch("/my-api/domain-session").then((r) => r.json());
const handle = showDoDomain({
token,
onVerified: ({ domain }) => {
console.log("connected:", domain);
location.reload();
},
onClose: ({ state }) => {
// "verified" | "pending" | "failed" | "unknown" — closing now tells you
// something, so you don't have to re-poll your own backend to find out.
if (state !== "verified") keepTheConnectDomainPromptVisible();
},
onError: (err) => {
if (err.code === "MOUNT_BLOCKED") {
// The iframe never mounted (host CSP, network, content blocker).
// Same session, full page — see "Origins & CSP" below.
location.assign(err.hostedUrl);
return;
}
console.error("connect flow failed:", err.type, err.code);
},
});
// handle.close() to dismiss it programmatically
API 密码
showDoDomain(options) → { close }
| 选项 | 类型 | 页:1 |
|---|---|---|
token | string | 要求。 会话符号( E)dd_sess_…从 POST /api/v1/sessions。 。 。 . |
baseUrl | string | 域名来源. 默认为 https://app.dodomain.io。 。 。 . |
onVerified | (detail: { domain?: string }) => void | 域能验出后起火. |
onClose | (detail: DoDomainCloseDetail) => void | 当模式被解除时会起火(回放点击,内流关闭, handle.close())),与会后已知的状态相通——见下文. 一个零弧 () => … 对照旧版本编写的处理器继续工作. |
onError | (detail: DoDomainWidgetError) => void | 当流量不能加载或报告会话错误时起火——见下文。 默认缺席(前:沉默). |
loadTimeoutMs | number | 等待主机流的负载握手需要多久才能将嵌入物视为失败. 默认 15000。 。 。 . |
返回一个控件 close()框中的信息为 原产地检查 反对
baseUrl,所以只有主机流才能触发回调. 必须在浏览器中运行 .
onError —— 说 DoDomainWidgetError
一个跨原产地的 Iframe的HTTP 404/500不会开火 onerror 或暴露可读内容,所以
被打碎的嵌入器曾经是完全沉默的. 每个 onError 细节带一个 code (单位:千美元)
hostedUrl (同一会话的整页流程),加a type数字 :
{ type: "load-timeout", code: "MOUNT_BLOCKED" }- 里面没有握手loadTimeoutMs(a 404, DNS 失败, 离线网络, 内容屏蔽器, 或主机页面 CSP —— 任何从来就不够 运行主机流量自己的JS.{ type: "load-error", code: "MOUNT_BLOCKED" }一个更快的信号 用于同样的事实: iframe属于自己error事件开火, 或者说 您的页面 CSP 报告封锁了帧 (单位:千美元)securitypolicyviolation打开frame-src编号 :child-src编号 :default-src)),着陆于 毫秒而不是等待出来loadTimeoutMs。 。 。 .{ type: "session-error", code: string }——主机页面上载并报告故障.code匹配主机页面本身的页内错误横幅所用的相同词汇 (单位:千美元)expired, (中文(简体) ),not_found, (中文(简体) ),invalid_request, (中文(简体) ),internal) (中文(简体) ). 两名制作人:averify()调用 自2026-08-18年以来,这一标志是: 当工作表显示时已死亡 打开 (单位:千美元)expired编号 :not_found以迷惑的态度降临你load-timeout换句话说 将此一个当作终端: 关闭工作表并薄荷新会话 而不是重试同样的事物.
code === "MOUNT_BLOCKED" 这是您需要的“嵌入在这里是不可能的”检查:
工作表从未出现,所以用户在工作表内所做的任何工作都无法成功——发送到
err.hostedUrl 换句话说 这是故意不叫的 CSP_BLOCKED: 从主页 a
CSP块,一个DNS故障和一个广告屏蔽器是无法区分的,所有四个都想要相同的
倒计时.
onClose —— 说 DoDomainCloseDetail
onClose 接收 { state, domain? },来源于流 自己的后米斯吉流量,所以
解雇并非含糊不清
state | 含义 |
|---|---|
verified | 流量报告已核实域(domain 已设定). 粘相——后期出错不能降级. |
pending | 流量挂起, 但用户在任何结果前关闭 . |
failed | 流量报告出错(例如a) verify() 并且从未被证实. |
unknown | 部件完全没有从流中听到 —— 把这个配给 MOUNT_BLOCKED onError。 。 。 . |
签名 connection.verified webhook仍然是真相的来源; state 是一个UI提示,和
浏览器中的任何内容都可以被偷取.
来源和CSP
部件从 iframe 中装入主机流 一个 源代码,因此是一个内容-安全政策
您的页面必须允许它进入 frame-src (浏览器掉回 child-src,则
default-src故你们可以随意决定:
Content-Security-Policy: frame-src https://app.dodomain.io;
https://app.dodomain.io生产来源—— 价值DODOMAIN_DEFAULT_ORIGIN(单位:千美元)packages/core/src/origin.ts),这是什么baseUrl默认为 和这个repo定义的单一地点.api.dodomain.io财务报告和审定财务报表connect.dodomain.io为: 同一用途的化妆品名称 没有 今天已经服役了——不要允许列入.- 如果你通过自己的
baseUrl(自营或中转), 批准来源. - 部件不向您的页面注入脚本、样式、字体或图像, 所以
frame-src这是 只有它需要的指示。 它会听自己的页面securitypolicyviolation事件 早期检测到一个区块——一个只读的收听器,在任何地方都没有报告.
主机URL倒置
如果帧不能挂起,请倒回同一会话全页——没有第二次API呼叫 符号已经是您的 :
showDoDomain({
token,
onError: (err) => {
if (err.code === "MOUNT_BLOCKED") location.assign(err.hostedUrl); // {baseUrl}/connect/{token}
},
});
hostedUrl 故意省略 embed编号 :origin编号 :theme iframe 中包含的查询参数 :
将流量放入嵌入式模式,这对顶级导航是错误的. 过
returnUrl 当您将会话薄荷时, 用户会返回您的应用程序.
见 src/index.ts 执行.