> ## 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 方案或 [Launch 方案](/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 讓使用者可透過單一登入驗證，安全地存取社群連結頁面。
你會在新的分頁、視窗或 view controller 中顯示此頁面，讓使用者連結他們的社群媒體帳號。

<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，因此你無法將 Ayrshare
  連結頁面嵌入或顯示在你網站的 iFrame 中。
</Note>

## 建立 Ayrshare 使用者設定檔

### 透過 API 建立設定檔

當新使用者在你的系統註冊，或當你的客戶在應用程式中點擊社群網路連結時，透過呼叫 [/profiles/create-profile](/apis/profiles/create-profile) RESTful 端點，或使用 [NPM](/packages-guides/nodejs) 或 [PyPi](/packages-guides/python) 套件，建立新的 Ayrshare 設定檔帳戶。

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

此呼叫會回傳使用者的 *PROFILE KEY*。此金鑰將用來代為使用者發文並管理他們的帳戶。你應將其儲存在安全的地方。

### 透過儀表板建立設定檔（內部團隊）

你的內部團隊也可直接從 **Developer Dashboard** 建立使用者設定檔——這對於測試、手動導入設定檔或一次性管理非常有用。這是團隊工具，並非面向客戶的流程：你的客戶永遠不會取得儀表板存取權，且一律透過 [JWT URL 連結頁面](#single-sign-on-with-jwt-authentication) 進行導入。對於正式環境的導入，請使用 [API](/apis/profiles/create-profile) 以程式方式建立設定檔，這樣每位新使用者都會自動配置。

<Card title="在儀表板中管理使用者設定檔" icon="link" href="/multiple-users/manage-user-profiles#using-the-dashboard" horizontal />

### 整合套件

在你以 Business 方案或 Launch 方案客戶進行導入時，你會收到個人化的整合套件，內含重要的設定與網域資訊、範例端點呼叫等。相關資訊請洽你的主要帳戶持有人。

你也可以在儀表板的 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 是建議用於每位客戶的導入路徑。你的使用者會直接與每個社群網路
  自行驗證——你永遠不會蒐集或儲存他們的社群憑證。如果你的團隊在測試時
  需要手動連結帳號，可透過儀表板進行，但這只是內部方便的做法，
  並非客戶應該的導入方式。
</Note>

### 白牌連結帳號頁面

由 JWT URL 開啟的連結頁面是使用者會看到的唯一 Ayrshare 介面，因此你應將它品牌化為自己的頁面。加入你的 logo 與自訂標頭、選擇要顯示哪些社群網路、設定頁面語言，並使用你自己的說明連結——搭配 [Max Pack](/additional/maxpack)，還可套用完整自訂 CSS 檔案、favicon、頁面標題與頁尾。這些選項只需由你的團隊在主要設定檔中設定一次，就會套用到你產生的每個 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 中加入以下 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() {
    // Open a new tab
    var newTab = window.open("https://profile.ayrshare.com?domain...");

    // Optional: Focus on the new tab
    newTab.focus();
  }
</script>
```

你可以控制「Close」按鈕，讓它將社群連結分頁重新導向到你選擇的頁面，或重新導向原始開啟者的分頁／視窗並關閉社群連結分頁。
可透過 redirect 參數，並在 redirect URL 的查詢參數中加入 `origin=true` 來達成。
詳情請參閱 [Generate JWT 端點](/apis/profiles/generate-jwt)。

### 關閉時重新導向

此外，如果你希望 `Close` 按鈕重新導向回你的頁面（在行動裝置上常用），請傳入 `redirect` GET 參數，其值為 *URL 編碼* 且以 https 開頭的字串。
更多細節請參閱 [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 接收通知。更多資訊請參閱 [Social Action Webhooks](/apis/webhooks/actions#social-action) 頁面。

你也可以使用 [user endpoint](/apis/user/profile-details) 取得使用者設定檔已連結的社群網路。

### 多組社群帳號

#### 概觀

每個使用者設定檔擁有一組社群媒體帳號，且對每個社群網路可建立一個連結。
如果你的使用者或客戶擁有多組社群媒體帳號（例如兩個 Facebook 粉絲專頁、兩個 Instagram 帳號、兩個 YouTube 頻道），你可以依照下列步驟管理這些多組社群媒體帳號：

1. **建立多個使用者設定檔** - 為使用者或客戶需要管理的每組社群帳號，[各建立一個獨立的使用者設定檔](/apis/profiles/create-profile)。

2. **儲存不同的 Profile Key** - 每個使用者設定檔會有各自唯一的 Profile Key，由建立使用者設定檔端點回傳。

3. **為設定檔加上標籤** - 為每個使用者設定檔設定 [Title](/apis/profiles/create-profile#param-title) 或 [tag](/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 粉絲專頁：「Joe's Downtown Bistro」</li>
  <li>Instagram：@joesdowntownbistro</li>
  <li>LinkedIn：Joe's Downtown Bistro 商家頁面</li>
</ul>

**餐廳據點 2：**

<ul className="custom-bullets">
  <li>Facebook 粉絲專頁：「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：Title 為「Joe's Downtown Bistro Accounts」</li>
  <li>使用者設定檔 2：Title 為「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 location)
   - Profile Key 2: xyz789... (Seaside location)
   ```

4. 當為 Downtown 據點發布特色菜單更新時，在 API 呼叫中使用 Profile Key 1。當為 Seaside 據點發布海鮮促銷時，使用 Profile Key 2。

透過建立多個使用者設定檔、適當地為它們 [設定 title](/apis/profiles/create-profile#param-title) 或 [加上 tag](/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 />