> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Business 版的 API 集成

> 让你的用户关联他们的社交媒体账户

Business Plan 或 [Launch Plan](/multiple-users/business-launch-overview) 集成的一项重要内容，是在 Ayrshare 中为你的用户或客户创建新的配置账户，并允许你的用户通过[社交关联页面](/multiple-users/user-integration)关联其社交网络。
你的每个用户都会被设置为一个 Ayrshare 用户配置。每个用户配置对每个社交网络可以拥有一个连接。

<Note>
  **这是接入客户的标准方式。** 你的用户通过下文所述的白标 JWT URL
  关联页面自行连接社交账户——
  他们从不需要登录 Ayrshare，也不会接触你的控制台。
  [控制台](/multiple-users/manage-user-profiles#using-the-dashboard) 专属于你的
  内部团队使用（创建和管理配置、测试，以及
  代表客户发帖）。
</Note>

## 集成工作流程

要将 Ayrshare 集成到你的应用中，你需要发起两次 API 调用：

1. 调用 [Create Profiles 接口](/apis/profiles/create-profile) 为你的用户创建新的 Ayrshare 配置。
2. 调用 [Generate JWT 接口](/apis/profiles/generate-jwt) 获取 JWT URL。

JWT URL 允许你的用户通过单点登录安全访问社交关联页面。
你可以在新标签页、窗口或视图控制器中展示该页面，让用户连接他们的社交媒体账户。

<img src="https://mintcdn.com/ayrshare-docs/6mPR4kmwNEz1kMbX/images/multiple-users/linking-flow.webp?fit=max&auto=format&n=6mPR4kmwNEz1kMbX&q=85&s=5a6d2569f89cefbb3ce85837bbd2a9c3" alt="连接用户配置的流程" width="3408" height="2069" data-path="images/multiple-users/linking-flow.webp" />

用户关联好社交媒体账户之后，你就可以通过 API 发帖、获取分析并管理他们的账户。

<Note>
  出于安全考虑，社交媒体平台要求用户通过浏览器完成认证，
  而不能通过后端服务器调用完成。这可以确保你的用户能够
  在每个平台的官方登录页面上直接登录，从而安全地关联其社交媒体账户。
  社交网络限制身份验证只能在其授权合作伙伴域名（例如 Ayrshare）下完成。
  它们同时也会屏蔽 iFrame，这意味着你无法在自己网站上通过 iFrame 嵌入或展示 Ayrshare
  的关联页面。
</Note>

## 创建 Ayrshare 用户配置

### 通过 API 创建配置

当新用户在你的系统中注册，或者当你的客户在你的应用中点击社交网络链接时，你可以通过调用 [/profiles/create-profile](/apis/profiles/create-profile) 这个 RESTful 接口来创建新的 Ayrshare 配置账户，也可以使用 [NPM](/packages-guides/nodejs) 或 [PyPi](/packages-guides/python) 包。

<Card title="Profiles" icon="code" href="/apis/profiles/overview" horizontal />

该调用会返回你用户的 *PROFILE KEY*。该密钥用于代表用户发帖并管理其账户。你应将其保存在安全的位置。

### 通过 Dashboard 创建配置（内部团队）

你的内部团队也可以直接在 **Developer Dashboard** 中创建用户配置——适合测试、手动接入某个配置或一次性的运维操作。这是团队工具，而非面向客户的流程：客户绝不应获得 Dashboard 访问权限，接入用户始终应通过 [JWT URL 关联页面](#single-sign-on-with-jwt-authentication) 进行。在生产环境的接入中，请通过 [API](/apis/profiles/create-profile) 以编程方式创建配置，以便每个新用户被自动开通。

<Card title="在 Dashboard 中管理用户配置" icon="link" href="/multiple-users/manage-user-profiles#using-the-dashboard" horizontal />

### 集成资料包

在你作为 Business Plan 或 Launch Plan 客户完成入驻时，你会收到一份个性化集成资料包，其中包含重要的搭建与域名信息、示例接口调用等。请与你的主账户持有人确认这些信息。

你也可以在 Dashboard 的 API 页面中获取或重置集成资料包。请务必先切换到 Primary Profile。

<img src="https://mintcdn.com/ayrshare-docs/6mPR4kmwNEz1kMbX/images/multiple-users/integration.webp?fit=max&auto=format&n=6mPR4kmwNEz1kMbX&q=85&s=ce8b1f0b733f87ad61d75f66029b84df" alt="Ayrshare Integration Package" width="900" height="200" data-path="images/multiple-users/integration.webp" />

## 使用 JWT 认证进行单点登录

Ayrshare 使用 JWT（JSON Web Token）对你的用户进行身份验证并完成对社交关联页面的单点登录。JWT 是一种传递数字签名信息的安全机制，可以让 Ayrshare 同时验证你和你用户的身份。

### 生成 JWT

你的应用将构造一个 JWT，其中包含你的 API Key、用户的 Profile Key 以及其他一些参数。该 JWT 将使用你的 1024 位私钥进行签名。

<Note>
  JWT token 的有效期为 5 分钟。如需更长的过期时间，请参见 [Max Pack](/additional/maxpack)。
</Note>

请使用 [Generate JWT 接口](/apis/profiles/generate-jwt) 由 Ayrshare 生成 token 及社交关联 URL。在新标签页或窗口中打开该社交关联 URL，以便你的用户轻松[关联其社交网络](/multiple-users/user-integration)。

<Note>
  JWT URL 是每一位客户推荐的接入方式。你的用户会直接在各个社交网络上完成身份验证——
  你永远不会收集或保存他们的社交
  凭据。如果你的团队在测试期间需要手动关联账户，可以从
  Dashboard 中进行，但这只是内部便利，而不是接入客户的方式。
</Note>

### 白标化关联账户页面

由于 JWT URL 打开的关联页面是用户唯一会看到的 Ayrshare 界面，你应该将其打造为你自己的品牌。添加你的 logo 和自定义头部、选择要展示的社交网络、设置页面语言，并使用你自己的帮助链接——通过 [Max Pack](/additional/maxpack) 还可以应用完整的自定义 CSS 文件、favicon、页面标题和页脚。这些选项由你的团队在 Primary Profile 下配置一次，之后对你生成的每个 JWT URL 均生效。

<Card title="白标化关联账户页面" icon="palette" href="/multiple-users/manage-user-profiles#white-label-the-connect-accounts-page" horizontal>
  查看关联页面所有品牌与自定义选项。
</Card>

### 自动登出当前配置会话

<Warning>
  **如何自动登出当前配置会话**

  如果某个配置已经登录，那么发送另一个配置的 JWT 并不会切换配置。这样做是为了让已登录用户获得更快的体验。在测试时，请先登出当前配置，再使用另一个配置发起 SSO 调用。已登录的配置在被显式登出之前会一直保持登录状态。

  不过，如果你有业务需要（例如用户经常在多个配置间切换，或你需要进行测试），可以在 SSO URL 中加入以下查询参数：

  `logout=true`

  例如：

  `https://profile.ayrshare.com?domain=[domain id]&jwt=[jwt token]&logout=true`

  这会强制登出，然后以新的配置登录。

  也请参见 [Generate JWT 接口](/apis/profiles/generate-jwt) 中如何自动添加登出。

  **警告**：使用自动登出会给用户带来性能上的延迟，因此如非必要，建议不要强制登出，也不要在生产环境中使用。
</Warning>

## 打开与关闭社交关联 URL

Social Accounts 页面上有一个 "Close" 按钮，用于关闭窗口并将你的用户返回你的网站。

### 打开社交关联 URL

打开社交关联 URL 时，我们建议使用 JavaScript 的 `window.open()` 函数，而不是 anchor 的 href。
"Close" 按钮通过 JavaScript 关闭窗口，而大多数浏览器只允许通过脚本打开的窗口才能被关闭。
你可以在自己的网站上使用下面的示例代码来启动社交关联窗口。

```html Window Open theme={"system"}
<div onclick="window.open('https://profile.ayrshare.com?domain...', '_blank')">
  Link Social Networks
</div>
```

或

```html Window Open Function theme={"system"}
<button onclick="openNewTabAndRedirect()">Open New Tab and Redirect</button>
<script>
  function openNewTabAndRedirect() {
    // 打开新标签页
    var newTab = window.open("https://profile.ayrshare.com?domain...");

    // 可选：聚焦到新标签页
    newTab.focus();
  }
</script>
```

你可以控制 "Close" 按钮的行为：要么将社交关联标签跳转到你选择的页面，要么跳转最初打开它的标签/窗口并关闭社交关联标签。
这可以通过 redirect 参数并在跳转 URL 的查询参数中添加 `origin=true` 来实现。
更多详情请参见 [Generate JWT 接口](/apis/profiles/generate-jwt)。

### 关闭时跳转

此外，如果你希望 `Close` 按钮跳转回你的页面（在移动端上通常很有用），请以 https 开头的\_URL 编码\_字符串形式传入 `redirect` GET 参数。
更多详情请参见 [Generate JWT 接口参数](/apis/profiles/generate-jwt#body-parameters)。

```javascript JWT URL theme={"system"}
https://profile.ayrshare.com?domain=[domain id]&jwt=[jwt token]&redirect=https%3A%2F%2Fmywebsite.com
```

跳转设置会被保存到该配置上，并在后续的 SSO 调用中即使不再传入 `redirect` 参数也依然生效。
要将 `Close` 按钮重置为直接关闭，请传入参数 `redirect=null`。

## 更多信息

### 用户关联或解绑通知

当用户关联或解绑某个社交网络时，你可以通过 webhook 收到通知。更多信息请参见[社交操作 Webhooks](/apis/webhooks/actions#social-action) 页面。

你也可以使用 [user 接口](/apis/user/profile-details) 获取用户配置已关联的社交网络。

### 多套社交账户

#### 概览

每个用户配置都对应一组社交媒体账户，且对每个社交网络可以建立一个连接。
如果你的用户或客户拥有多套社交媒体账户，例如两个 Facebook Page、两个 Instagram 账户和两个 YouTube 频道，你可以按以下步骤管理这些多套社交媒体账户：

1. **创建多个用户配置** —— 在 Ayrshare 系统中为你的用户或客户需要管理的每一套社交账户[分别创建独立的用户配置](/apis/profiles/create-profile)。

2. **保存唯一的 Profile Key** —— 每个用户配置都有自己独立的 Profile Key，由创建用户配置的接口返回。

3. **为你的配置打标** —— 为每个用户配置[设置标题](/apis/profiles/create-profile#param-title)或[标签](/apis/profiles/create-profile#param-tags)，以清晰标识它们所关联的社交媒体账户（例如 “Facebook Page A” 与 “Facebook Page B”）。

4. **在你的数据库中做映射** —— 在你自己的系统中，将相关的 Profile Key 与对应的用户或客户关联起来。

5. **使用相应的 Profile Key** —— 当为某个特定社交账户发帖或获取分析时，使用与该账户对应的 Profile Key。例如，要发布到 Facebook Page A，就使用连接到 Facebook Page A 的用户配置对应的 Profile Key。

#### 示例

我们来看一个多客户账户的实际场景：

<ul className="custom-bullets">
  <li>**客户：** Joe's Restaurant Chain，两个门店</li>
</ul>

Joe 需要为每个餐厅门店维护独立的社交媒体账户：

**门店 1：**

<ul className="custom-bullets">
  <li>Facebook Page： “Joe's Downtown Bistro”</li>
  <li>Instagram：@joesdowntownbistro</li>
  <li>LinkedIn：Joe's Downtown Bistro 企业主页</li>
</ul>

**门店 2：**

<ul className="custom-bullets">
  <li>Facebook Page： “Joe's Seaside Grill”</li>
  <li>Instagram：@joesseasidegrill</li>
  <li>LinkedIn：Joe's Seaside Grill 企业主页</li>
</ul>

**实现方案：**

1. 在 Ayrshare 中创建两个独立的用户配置：

<ul className="custom-bullets">
  <li>用户配置 1：标题为 “Joe's Downtown Bistro Accounts”</li>
  <li>用户配置 2：标题为 “Joe's Seaside Grill Accounts”</li>
</ul>

2. 将相应的社交账户连接到各自的配置：

<ul className="custom-bullets">
  <li>配置 1：连接 Downtown Bistro 的 Facebook、Instagram 和 LinkedIn</li>
  <li>配置 2：连接 Seaside Grill 的 Facebook、Instagram 和 LinkedIn</li>
</ul>

3. 在你的数据库中保存两个 Profile Key，并将它们与 Joe 的账户关联：

   ```
   Client: Joe's Restaurant Chain
   - Profile Key 1: abc123... (Downtown 门店)
   - Profile Key 2: xyz789... (Seaside 门店)
   ```

4. 当为 Downtown 门店发布特色菜单更新时，在 API 调用中使用 Profile Key 1；当为 Seaside 门店发布海鲜促销时，则使用 Profile Key 2。

通过创建多个用户配置，为它们设置合适的[标题](/apis/profiles/create-profile#param-title)或[标签](/apis/profiles/create-profile#param-tags)，并在你的系统中把它们与同一位用户或客户关联起来，你就可以使用 Ayrshare 管理同一批平台下多套社交媒体账户。
这种方式让你能够针对每个具体账户进行精准发帖和分析获取。

### 后续步骤

有关用户体验的更多详情，请参见：

<Card title="用户集成" icon="link" href="/multiple-users/user-integration" horizontal />

用户完成社交媒体关联后，你就可以通过 /post 和 /profile 等接口开始
代表他们发帖。

<Card title="Post API" icon="code" href="/apis/post/overview" horizontal />

<Card title="Profiles API" icon="code" href="/apis/profiles/overview" horizontal />