嵌入

在你自己的网站上放一条 Debaty 帖子

用一段复制粘贴的代码就能嵌入单条帖子——没有 cookie，没有追踪，所以你的访客根本不用为它去关掉一个 cookie 横幅。

代码片段

把这段代码贴在帖子应该出现的位置。blockquote 就是内容本身——搜索引擎、RSS 阅读器和屏幕阅读器都能读到，即使 JavaScript 关闭也一样。脚本会把它替换成一张会实时自动调整大小的卡片。

<blockquote class="debaty-embed" data-debaty-post="<post-id>">
  <p>De posttekst — leesbaar zonder JavaScript.</p>
  <p>— Naam (@handle) · <a href="https://debaty.com/nl/bubbel/<post-id>">https://debaty.com/nl/bubbel/<post-id></a></p>
</blockquote>
<script async src="https://debaty.com/embed.js" charset="utf-8"></script>

你不用手动写这些：每条帖子的分享菜单里都有“嵌入”，代码是现成生成的——连 blockquote 里的帖子正文都包含在内。

嵌入直播博客

除了帖子，你还可以嵌入整个直播博客：用 data-debaty-liveblog 加上直播博客 id，代替 data-debaty-post。卡片会显示标题、主持人、最新的三条更新，以及指向完整记录的链接，并在直播博客开启期间每三十秒自动刷新一次——不使用 cookie，也不向任何第三方发送请求。直播博客一旦关闭，刷新就会停止，卡片会显示结束摘要。

<blockquote class="debaty-embed" data-debaty-liveblog="<liveblog-id>">
  <p><strong>De titel van het liveblog</strong></p>
  <p>De intro — leesbaar zonder JavaScript.</p>
  <p>— Naam (@handle) · <a href="https://debaty.com/nl/liveblog/<liveblog-id>">https://debaty.com/nl/liveblog/<liveblog-id></a></p>
</blockquote>
<script async src="https://debaty.com/embed.js" charset="utf-8"></script>

工作原理

embed.js（约 2 kB，无任何依赖）会找到带 data-debaty-post 的 blockquote，并把它们替换成指向该帖子嵌入页面的 iframe。iframe 会测量自身大小，并通过 postMessage 报告高度；embed.js 只接受来自我们自己 origin 的这类消息，而且只接受它自己放置的 iframe 发来的消息。卡片里的链接会在新标签页中打开 Debaty。

没有 cookie，没有追踪

嵌入文档不设置任何 cookie，不读取会话，也完全不发出任何第三方请求——用系统字体、自己的 CSS，图片也只来自我们自己的 origin。所以没有任何需要征得同意的东西：你放这个嵌入时无需承担 cookie 横幅义务，而且它在完全屏蔽第三方 cookie 的浏览器（比如 Safari）里也照样能用。

你想自己搭 iframe，而不是通过 embed.js？那就给它加上这个 sandbox 属性——卡片需要的就这么多：

<iframe src="https://debaty.com/embed/post/<post-id>"
        sandbox="allow-scripts allow-same-origin allow-popups"></iframe>

主题和语言

默认情况下，卡片会跟随访客的配色方案（浅色/深色）。在 blockquote 上用 data-debaty-theme="light" 或 "dark" 把它固定住；卡片标签的语言用 data-debaty-lang="nl" 或 "en" 来选。

oEmbed

对于会说 oEmbed 的 CMS 和编辑器（WordPress、类 Mastodon 应用、笔记应用），我们有一个符合 oembed.com 规范的端点：type 为 rich，代码片段放在 html 里。height 是 null——高度要等内容渲染出来才知道；embed.js 会实时测量它。maxwidth 会被遵守，但上限是我们设定的 600。

GET /api/oembed?url=https%3A%2F%2Fdebaty.com%2Fnl%2Fbubbel%2F<post-id>&format=json

{
  "version": "1.0",
  "type": "rich",
  "provider_name": "Debaty",
  "author_name": "…",
  "html": "<blockquote class=\"debaty-embed\" …>…</blockquote><script async src=\"…/embed.js\"></script>",
  "width": 600,
  "height": null
}

每个公开的帖子页面都带有发现链接（<link rel="alternate" type="application/json+oembed">），所以 oEmbed 使用方只需要普通的固定链接就够了。

那发布者小组件呢？

这是两个不同的产品。帖子嵌入（本页）展示一条已有的 Debaty 帖子，可放在任何地方，无需注册。发布者小组件是放在你自己文章下方的评论面板：显示你读者的评论，带审核队列和域名白名单，通过你的发布者账号管理。

前往发布者小组件 →