Profile-Key 创建。你这一侧不需要签名任何内容,流程中也没有 private key。唯一的例外是自行签名 token 的较早集成。参阅自签名 token(旧方式)。
三种关联方式
三种形态,且前两种是同一个集成。请按流程选择——它们并不互斥,很多集成在接入阶段使用托管页面,之后在应用内使用小组件。两个小组件行是同一个集成,而不是两个。一次
init 同时给你两者:在需要我们按钮的地方挂载框架,在其他任何地方从你自己的按钮调用 popup()。它们共享同一个会话,并在同一组处理器上报告结果。直连模式(Direct Mode)是不带我们脚本的同一个弹窗——适用于带有严格 Content-Security-Policy 的页面、服务器端渲染的页面或原生应用。在那里由你自己打开并监视弹窗。拿不准? 从托管关联页面开始。它不需要 Max Pack,也不需要额外参数,是最快跑通的路径——之后迁移到小组件也不会改变会话的创建方式。创建链接
在请求头中带上用户的Profile-Key,调用创建 Link Session。对托管页面来说,这就是完整的请求:
cURL
url:
Linking URL
这段 1 分钟的视频演示了如何创建链接。它录制于 link session 之前,因此仍然演示了发送 Private
Key——该步骤已不再需要,视频中展示的其他内容均保持不变。
发送链接 URL
打开链接 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
安全
会话 token 位于链接 URL 的查询字符串中。任何会记录 URL 的地方都可能记录下它:用户的浏览器历史记录、代理和服务器日志、分析工具,以及跳转服务。 为降低风险:- 不要在你自己的系统中记录完整的 URL。 改为记录 profile 和时间。
- 把 URL 直接发给用户。 不要让它经过短链接服务、跳转追踪器或邮件点击追踪。Connect Accounts 邮件发送链接时不使用点击追踪。
- 保持较短的有效窗口。 使用能满足你需求的最短
expiresIn(Max Pack)。 - 吊销你认为已泄露的链接。 使用吊销 Link Session 即可。
Profile Key
Profile-Key 指明链接对应哪个 User Profile。在 Ayrshare 开发者控制台切换到该 profile 即可
找到它。
创建链接不需要 Private Key。 通过 API 创建的链接不签名,因此无需从文件读取任何内容,也无需粘贴到代码里。旧的
privateKey 参数仍会被接受并忽略,所以现有集成继续工作。如果你的集成自行签名 token,请保留你的 private.key。参阅自签名 token(旧方式)。切换 Profile
如果某个 profile 已经登录,打开另一个 profile 的链接不会切换 profile——这是有意为之,它让已经 在场的用户获得更快的体验。要强制切换,请参见 自动登出 Profile 会话。Instagram 关联方式
Instagram 账户可以通过两种方式进行关联:直接使用 Instagram Login,或通过一个已关联的 Facebook Page。当用户点击 Instagram 按钮时启动哪种 流程,通常由账户级别的 Instagram Login 设置决定。instagramLinkMethod body 参数可为单个链接覆盖该设置:
Instagram Link Method
- 它不会更改账户级别的设置,也不会影响任何其他链接。
- 省略它时应用账户级别的设置,与以往行为完全一致。
- 非法值会返回
400,并列出合法值(instagram、facebook)。 - 在选择之前,请查看 功能差异 ——某些 Instagram 功能(例如 hashtag 搜索和合作发布)仅在使用 Facebook Page 认证时可用。
Connect Accounts 邮件
Ayrshare 可以替你把链接通过邮件发送给用户,让他们无需访问你的应用即可进入自己的关联页面。请与 更长的expiresIn 搭配使用——默认的 5 分钟很少能撑过收件箱。
Connect Accounts JSON
email 对象内的每个字段都是必填的。 缺少任何一个都会导致发送失败。
Example Contact Email Request
emailSent 中报告结果:
Example Contact Email Response
emailSent: false 和一个 emailError 对象,这样你可以通过其他方式把链接发给用户:
Example Failed Email Response
emailError:要么发送失败,要么 email 对象缺少必填字段(此时 details 会列出缺少的字段)。emailSent: false 但没有 emailError 表示没有请求发送邮件。缺少 to 则不同:整个请求会被拒绝,并返回 code: 188。
Connect Accounts 邮件示例
以下是打开社交关联页面的邮件示例:
Social Connect Hub <connect@socialconnecthub.com>
移动应用
请在系统浏览器中打开链接 URL,绝不要使用嵌入式 webview:Google 会以disallowed_useragent
拒绝登录,Meta 则直接屏蔽。你的用户会看到社交网络自己的错误页面,你这一侧无论怎么改都无济于事。
- iOS ——
ASWebAuthenticationSession或SFSafariViewController。 - Android —— Chrome Custom Tabs。
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。自签名 token(旧方式)
一些较早的集成会自行构建链接 URL。它们用自己 Integration Package 中的private.key 签名 token,并通过 ?jwt= 传入。
这种方式仍然可用,并且没有移除日期。 不建议在新集成中使用。请改用创建 Link Session。
如果你的集成自行签名 token:
- 继续使用你的
private.key,并妥善保密。 - 自签名链接无法通过 link session 端点查询或吊销。
- 不要重置你的 Integration Package。重置会停用你当前的域名及其密钥,因此你已经发出的链接将无法再使用,你也无法再签名新的链接。
- 自签名链接只有在其 token 设置了
exp时间时才会过期。expiresIn和 link session 的默认有效期对它不适用,因此请把这个时间设得短一些。 - 请像对待密码一样对待自签名链接的 URL。如果某个 URL 可能已泄露,请在控制台的 API 页面重置你的 API Key,然后更新你的集成以使用新的 key。这可以保护你的账户,但不一定能让已泄露的链接失效。如需让该链接失效,请联系支持团队。