Skip to main content
你的用户自己关联他们的社交账号——他们直接在每个社交网络上完成身份验证,你永远不会看到或存储他们的凭据。本页的全部内容,就是如何把他们带到那个时刻,以及如何得知结果。 所有路径都有一个共同点:一个 link session(关联会话),通过创建 Link Session、使用你的 API Key 和 Profile-Key 创建。你这一侧不需要签名任何内容,流程中也没有 private key。

三种关联方式

三种形态,且前两种是同一个集成。请按流程选择——它们并不互斥,很多集成在接入阶段使用托管页面,之后在应用内使用小组件。
两个小组件行是同一个集成,而不是两个。一次 init 同时给你两者:在需要我们按钮的地方挂载框架,在其他任何地方从你自己的按钮调用 popup()。它们共享同一个会话,并在同一组处理器上报告结果。直连模式(Direct Mode)是不带我们脚本的同一个弹窗——适用于带有严格 Content-Security-Policy 的页面、服务器端渲染的页面或原生应用。在那里由你自己打开并监视弹窗。拿不准? 从托管关联页面开始。它不需要 Max Pack,也不需要额外参数,是最快跑通的路径——之后迁移到小组件也不会改变会话的创建方式。

创建链接

在请求头中带上用户的 Profile-Key,调用创建 Link Session。对托管页面来说,这就是完整的请求:
cURL
你会得到一个携带短期有效、不透明 token 的 url:
Linking URL
你还可以查看链接是否已被打开,并在过期前吊销它。
这段 1 分钟的视频演示了如何创建链接。它录制于 link session 之前,因此仍然演示了发送 Private Key——该步骤已不再需要,视频中展示的其他内容均保持不变。

发送链接 URL

链接 URL 会让你的用户登录到他们的 profile,因此请像对待密码一样对待它。通过你信任的渠道发送,不要 记录到日志中,也不要转交给第三方。它在整个有效期内都可以使用,因此重新加载或重试 OAuth 都没问题—— 但每个链接只发给一位用户,并为每个人单独创建链接。

打开链接 URL

请在新的浏览器标签页、窗口或 View Controller 中打开它。你可以控制该窗口的 关闭或跳转。
社交网络不允许在 iFrame 中打开托管关联页面,也不允许对已获批准的合作伙伴来源 profile.ayrshare.com 进行混淆处理。如果你希望关联发生在你自己的页面内部, 嵌入式小组件正是为此而生:它的框架由 Ayrshare 的源提供服务,是受支持的实现方式。

得知何时完成

两种信号,任选其一:
  • 关联完成事件 —— 在创建链接时设置 origin, 关联窗口会在事件发生时向你的页面发送 connect:success、connect:error 和 connect:cancelled。无需轮询。
  • 获取 Link Session —— 报告 completedAt、 lastCompletedAt 和 completedNetworks。这是原生应用的信号,也是 Telegram 唯一的信号—— 它在带外(out of band)完成。

链接有效期

链接默认有效期为 5 分钟。之后请创建新的链接。 使用 Max Pack 时,可通过 expiresIn(以分钟为单位)延长该窗口——最长 2880 分钟 (48 小时),这是 API 接受的最大值:
Expires In
更长的窗口正是让通过邮件发送链接变得可行的原因——需要重新连接掉线账号 的用户可以直接从你的邮件进入社交网络,而无需先访问你的应用。
请与你的安全团队评估链接应保持多长的有效期。窗口越长,被截获的链接可用的时间就越长。如果链接 泄露,你可以吊销它,而不必等它过期。

Profile Key

Profile-Key 指明链接对应哪个 User Profile。在 Ayrshare 开发者控制台切换到该 profile 即可 找到它。
Private Key 已不再使用。 链接不再签名,因此无需从文件读取任何内容,也无需粘贴到代码里。 旧的 privateKey 参数仍会被接受并忽略,所以现有集成继续工作,Integration Package 中的 private.key 文件可以不再使用。

切换 Profile

如果某个 profile 已经登录,打开另一个 profile 的链接不会切换 profile——这是有意为之,它让已经 在场的用户获得更快的体验。要强制切换,请参见 自动登出 Profile 会话。 Instagram 账户可以通过两种方式进行关联:直接使用 Instagram Login,或通过一个已关联的 Facebook Page。当用户点击 Instagram 按钮时启动哪种 流程,通常由账户级别的 Instagram Login 设置决定。 instagramLinkMethod body 参数可为单个链接覆盖该设置:
Instagram Link Method
该覆盖在链接的整个生命周期内生效,包括跨越 Instagram/Facebook 授权跳转。需要注意几点:
  • 它不会更改账户级别的设置,也不会影响任何其他链接。
  • 省略它时应用账户级别的设置,与以往行为完全一致。
  • 非法值会返回 400,并列出合法值(instagram、facebook)。
  • 在选择之前,请查看 功能差异 ——某些 Instagram 功能(例如 hashtag 搜索和合作发布)仅在使用 Facebook Page 认证时可用。

Connect Accounts 邮件

Ayrshare 可以替你把链接通过邮件发送给用户,让他们无需访问你的应用即可进入自己的关联页面。请与 更长的 expiresIn 搭配使用——默认的 5 分钟很少能撑过收件箱。

Connect Accounts JSON

email 对象内的每个字段都是必填的。 缺少任何一个都会导致发送失败。
Example Contact Email Request
expiresIn 是顶层参数,不属于 email 对象。嵌套在 email 内会被忽略,你的用户拿到的 链接将在 5 分钟后过期。
响应会在 emailSent 中报告结果:
Example Contact Email Response
发送失败不会以 emailSent: false 的形式返回——而是返回 code: 333。因此 false 表示 没有请求发送邮件。

Connect Accounts 邮件示例

以下是打开社交关联页面的邮件示例: Connect Accounts email 邮件将从以下地址发出: Social Connect Hub <connect@socialconnecthub.com>

移动应用

请在系统浏览器中打开链接 URL,绝不要使用嵌入式 webview:Google 会以 disallowed_useragent 拒绝登录,Meta 则直接屏蔽。你的用户会看到社交网络自己的错误页面,你这一侧无论怎么改都无济于事。
  • iOS —— ASWebAuthenticationSession 或 SFSafariViewController。
  • Android —— Chrome Custom Tabs。
由于原生应用没有可供发送事件的浏览器窗口,请改为通过 获取 Link Session 获取结果。将 origin 设置为你的自定义 scheme(myapp://connected),让页面有办法回到你的应用。

移动端代码示例

请将 linkingURL 替换为创建 Link Session 返回的 url。

测试

建议首先在 Postman 中创建链接。你的 Integration Package——位于控制台 Primary Profile 的 API Key 页面——包含一个示例 Postman 配置。导入它,在 profileKey body 字段中填入你的 Profile Key,然后点击 Send。 示例配置仍会预填 privateKey 和 domain。privateKey 会被忽略;除非你的账户拥有多个关联 域名,否则可以清空 domain。 你也可以从 Postman 生成代码。

Bubble.io

Bubble linking URL

旧端点:generateJWT

生成链接 URL(generateJWT)完成同样的工作,并且已弃用—— 完全受支持、没有移除日期,你已经发出的链接也不会有任何变化。它自己的页面记录了它的参数, 包括如今被接受并忽略的那三个。两个端点使用同一个校验器,因此本页的所有内容对两者都适用。迁移时唯一值得了解的差异: generateJWT 容忍三种「创建 Link Session」会拒绝的情况——allowedSocial 中无法识别的网络、 只提供一半的 X 凭据、以及非字符串的 redirect。