你需要哪种界面
三种形态,且前两种是同一个集成。本页是你自己构建的那一种。直连模式就是第三行的弹窗,只是没有我们的脚本。 如果你的页面可以加载脚本,
小组件会替你完成本页的一切——它自己打开并监视弹窗,还能嵌入
框架。当你的页面无法加载第三方脚本,或界面是原生应用而非浏览器时,直连模式才是你需要的。

你的按钮,你的页面。弹窗是用户唯一会看到的我们的东西,而且只在网络需要的时间内出现。
你要构建的内容
四个步骤。第一步在你的服务器上,其余在你的页面中。1
为单个网络创建会话
从你的后端调用创建 Link Session,带上
你会得到一个指向单网络连接页面的
mode: "connect"、network,以及你页面运行所在的 origin。Your backend
url,而没有 token——token 在 URL 内部。请把整个 URL
当作密码对待:它会让你的用户登录其 User Profile。2
在点击处理器中同步打开它
弹窗必须由
window.open 在点击处理器本身之内打开。浏览器只在仍在处理用户点击时才允许
弹窗,而这个许可撑不过一次 await——因此先获取 URL 再在回调中打开,必然会被弹窗拦截。请在渲染按钮时或用户悬停按钮时获取 URL。到点击时你应该已经拿到它了。Your page
3
监听结果
因为你传入了
origin,弹窗会为其中发生的每件事向你的页面发送事件:connect:success、
connect:error、connect:cancelled,以及其间的进度事件。每次连接恰好到达这三者之一。关联完成事件提供完整的事件表和可直接复制的监听器
——上面的 listenForOutcome 就是那段代码。其中有两处很容易漏掉,且都会造成真实的 bug:- 检查
event.origin,与你打开的 URL 的 origin 比对。任何页面都可以向你的窗口发送 消息,而 origin 是消息中唯一无法伪造的部分。 - 轮询
popup.closed,并在得出结论前留出短暂的宽限期。用户手动关闭的弹窗什么也不会 发送,而没有宽限期,一次成功的连接可能会被报告为已取消。
4
处理每种结局
各网络注意事项
大多数网络就是一个弹窗,仅此而已:你的用户点击、在网络上授权、弹窗关闭。以下是构建前值得了解的 例外。X 需要你自己的 API Key
X 需要你自己的 API Key
直连模式下的 X 使用你的 X Developer App 凭据,在创建会话时通过
创建 Link Session 的
X-Twitter-OAuth1-Api-Key 和
X-Twitter-OAuth1-Api-Secret header 提供。不带这些 header 为 twitter 或 x 创建的会话会在弹窗打开时被拒绝:你的用户被告知该
连接不可用且看不到任何表单,你的页面收到带 message 且无 code 的 connect:error。
这是有意的。缺失的凭据是你的,不是你用户的,绝不能要求终端用户输入你的 API Key。对比 Bluesky:应用密码(app password)是终端用户自己的凭据——连接页面确实会收集它,在弹窗
内的表单中。Facebook 在 Meta 登录前显示一个按钮
Facebook 在 Meta 登录前显示一个按钮
network: "facebook" 会在弹窗中显示一个按钮,Meta 自己的登录由那次点击打开——Meta 要求其
登录必须由托管其 SDK 的页面内的点击发起。你的用户点击两次而不是一次;其余没有任何不同。当 Instagram 通过 Facebook Page 关联时行为相同——即会话带有
instagramLinkMethod: "facebook",或你账户的
Instagram Login 设置选择了该流程时。
使用直接 Instagram Login 则没有额外按钮。Bluesky 和 Telegram 显示页面内容,而非跳转
Bluesky 和 Telegram 显示页面内容,而非跳转
两者都不会把你的用户送往网络登录页。弹窗改为渲染内容:Bluesky 是句柄和应用密码表单,
Telegram 是一个待使用的验证码。结果事件在两种情况下都相同。X 不属于这一组。会话带上你的 Key 时,它无需向你的用户询问任何内容即可完成;不带时则被拒绝
——见上文。
Telegram 在带外完成
Telegram 在带外完成
Telegram 显示一个验证码而不跳转到任何地方,连接在你的用户使用该验证码时完成——那时弹窗已经
不在了。没有可等待的浏览器事件,因此请轮询获取 Link Session
并关注
completedNetworks。Facebook Groups 无法通过这种方式连接
Facebook Groups 无法通过这种方式连接
Facebook Groups 不是关联目标,因此
network: "fbg" 在创建会话时返回 code: 508。WhatsApp 在直连模式下可用。它会在弹窗中打开 Meta 的 Embedded Signup,结果事件与其他
任何网络相同。原生应用
原生应用在系统浏览器中打开同一个url,并通过轮询
获取 Link Session 得知结果。将 origin 设置为你的自定义
scheme(myapp://connected),让页面有办法回到你的应用;自定义 scheme 无法接收事件,因为没有
可供发送的浏览器窗口。
- iOS ——
ASWebAuthenticationSession或SFSafariViewController。 - Android —— Chrome Custom Tabs。
直连模式的要求
- Max Pack。没有它创建 connect 模式的会话会返回
code: 504, 无论请求中还写了什么。 - 每个会话都要有
origin。没有允许列表,也没有注册步骤——每次调用时发送即可。省略它返回code: 505;不是httpsorigin、自定义 scheme 或http://localhost的值返回code: 506。 - 一个你的账户已启用的
network。无法识别的名称返回code: 508;能识别但你的账户未启用 的返回code: 509,你可以在 社交网络页面自行修复。 - 不要有
allowedSocial。它不能与network组合(code: 507)——单网络会话本身就是 自己的允许列表。
后续步骤
关联完成事件
弹窗发送的每个事件,以及接收它们的监听器。
相关内容
创建 Link Session
mode、origin 和 network 参数,以及响应形态。获取 Link Session
当你无法使用弹窗时,轮询获取完成情况。