Business 版 API 整合

Business 方案或 Launch 方案整合中一個重要的部分，是在 Ayrshare 為你的使用者或客戶建立新的設定檔帳戶，並讓使用者透過社群連結頁面連結他們的社群網路。你的每位使用者都會被設定為一個 Ayrshare 使用者設定檔。每個使用者設定檔對每個社群網路可以有一個連結。

這是導入客戶的標準做法。 你的使用者透過下述的白牌 JWT URL 連結頁面自行連結社群帳號——他們永遠不會登入 Ayrshare，也永遠不會操作你的儀表板。儀表板保留給你的內部團隊（用於建立與管理設定檔、測試，以及代客戶發文）。

整合流程

要將 Ayrshare 整合到你的應用程式，你需要進行兩個 API 呼叫：

呼叫 Create Profiles 端點為你的使用者建立新的 Ayrshare 設定檔。
呼叫 Generate JWT 端點取得 JWT URL。

JWT URL 讓使用者可透過單一登入驗證，安全地存取社群連結頁面。你會在新的分頁、視窗或 view controller 中顯示此頁面，讓使用者連結他們的社群媒體帳號。

當使用者連結社群媒體帳號後，你就可以透過 API 發布貼文、取得分析並管理他們的帳號。

基於安全考量，社群媒體平台要求使用者透過瀏覽器進行驗證，無法透過後端伺服器呼叫完成。這確保你的使用者能透過每個平台的官方登入頁面安全地連結社群媒體帳號。社群網路將驗證限制在其授權的合作夥伴網域（例如 Ayrshare）進行。它們也會封鎖 iFrame，因此你無法將 Ayrshare 連結頁面嵌入或顯示在你網站的 iFrame 中。

建立 Ayrshare 使用者設定檔

透過 API 建立設定檔

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

Profiles

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

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

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

在儀表板中管理使用者設定檔

整合套件

在你以 Business 方案或 Launch 方案客戶進行導入時，你會收到個人化的整合套件，內含重要的設定與網域資訊、範例端點呼叫等。相關資訊請洽你的主要帳戶持有人。你也可以在儀表板的 API 頁面中取得或重設整合套件。請先切換到你的主要設定檔（Primary Profile）。

使用 JWT 驗證進行單一登入

Ayrshare 使用 JWT（JSON Web Token）驗證你的使用者並執行社群連結頁面的單一登入。JWT 是一種安全的機制，可傳遞經數位簽章的資訊，讓 Ayrshare 能驗證你與你的使用者。

產生 JWT

你的應用程式將建立一個 JWT，內含你的 API Key、使用者 Profile Key 與其他幾個參數。此 JWT 會以你的 1024 位元私密金鑰簽章。

JWT token 有效期為 5 分鐘。若需要更長的過期時間，請參閱 Max Pack。

請使用 Generate JWT 端點讓 Ayrshare 建立 token 與社群連結 URL。在新的分頁或視窗中開啟社群連結 URL，讓使用者能輕鬆連結他們的社群網路。

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

白牌連結帳號頁面

由 JWT URL 開啟的連結頁面是使用者會看到的唯一 Ayrshare 介面，因此你應將它品牌化為自己的頁面。加入你的 logo 與自訂標頭、選擇要顯示哪些社群網路、設定頁面語言，並使用你自己的說明連結——搭配 Max Pack，還可套用完整自訂 CSS 檔案、favicon、頁面標題與頁尾。這些選項只需由你的團隊在主要設定檔中設定一次，就會套用到你產生的每個 JWT URL。

白牌連結帳號頁面

查看連結頁面所有可用的品牌化與客製化選項。

自動登出設定檔工作階段

如何自動登出目前的設定檔工作階段如果某個設定檔已登入，傳送另一個設定檔的 JWT 不會切換設定檔。這是為了讓已登入使用者的體驗更快速。測試時，請先登出目前的設定檔，再以不同的設定檔進行 SSO 呼叫。已登入的設定檔在明確登出前會保持登入狀態。不過，如果你有業務需要（例如使用者常常存取多個設定檔，或需要進行測試），可在 SSO URL 中加入以下 URL 參數：logout=true例如：https://profile.ayrshare.com?domain=[domain id]&jwt=[jwt token]&logout=true這會強制登出，然後登入新的設定檔。也請參閱 Generate JWT 端點以自動加入登出。警告：使用自動登出會為使用者帶來效能延遲，除非有需要，否則我們建議不要強制登出，也不要在正式環境使用。

開啟與關閉社群連結 URL

Social Accounts 頁面有一個「Close」按鈕，可關閉視窗並將使用者帶回你的網站。

開啟社群連結 URL

在開啟社群連結 URL 時，建議使用 JavaScript 的 window.open() 函式，而非 anchor href。「Close」按鈕使用 JavaScript 關閉視窗，且大多數瀏覽器只允許透過指令碼開啟的視窗被關閉。你可以在網站上使用以下範例程式碼來開啟社群連結視窗。

Window Open

<div onclick="window.open('https://profile.ayrshare.com?domain...', '_blank')">
  Link Social Networks
</div>

或

Window Open Function

<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 端點。

關閉時重新導向

此外，如果你希望 Close 按鈕重新導向回你的頁面（在行動裝置上常用），請傳入 redirect GET 參數，其值為 URL 編碼 且以 https 開頭的字串。更多細節請參閱 Generate JWT 端點參數。

JWT URL

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 頁面。你也可以使用 user endpoint 取得使用者設定檔已連結的社群網路。

多組社群帳號

概觀

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

建立多個使用者設定檔 - 為使用者或客戶需要管理的每組社群帳號，各建立一個獨立的使用者設定檔。
儲存不同的 Profile Key - 每個使用者設定檔會有各自唯一的 Profile Key，由建立使用者設定檔端點回傳。
為設定檔加上標籤 - 為每個使用者設定檔設定 Title 或 tag，以清楚識別它們對應到哪組社群媒體帳號（例如「Facebook Page A」與「Facebook Page B」）。
在你的資料庫中對應 - 在你自己的系統中，將所有相關的 Profile Key 關聯至對應的使用者或客戶。
使用適當的 Profile Key - 當你要發布內容或取得特定社群帳號的分析時，使用與該帳號關聯的 Profile Key。例如，要發布到 Facebook Page A，就使用連結到 Facebook Page A 的使用者設定檔的 Profile Key。

範例

我們來看一個多客戶帳號的實際情境：

客戶： Joe’s Restaurant Chain（有兩個據點）

Joe 需要為每個餐廳據點建立獨立的社群媒體帳號： 餐廳據點 1：

Facebook 粉絲專頁：「Joe’s Downtown Bistro」
Instagram：@joesdowntownbistro
LinkedIn：Joe’s Downtown Bistro 商家頁面

餐廳據點 2：

Facebook 粉絲專頁：「Joe’s Seaside Grill」
Instagram：@joesseasidegrill
LinkedIn：Joe’s Seaside Grill 商家頁面

實作方式：

在 Ayrshare 建立兩個獨立的使用者設定檔：

使用者設定檔 1：Title 為「Joe’s Downtown Bistro Accounts」
使用者設定檔 2：Title 為「Joe’s Seaside Grill Accounts」

為每個設定檔連結對應的社群帳號：

設定檔 1：連結 Downtown Bistro 的 Facebook、Instagram 與 LinkedIn
設定檔 2：連結 Seaside Grill 的 Facebook、Instagram 與 LinkedIn

將兩個 Profile Key 儲存到你的資料庫，並關聯至 Joe 的帳戶：

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

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

透過建立多個使用者設定檔、適當地為它們設定 title 或加上 tag，並在你的系統中將它們關聯至同一位使用者或客戶，你就能透過 Ayrshare 管理同一位使用者在相同平台上的多組社群媒體帳號。這種方式讓你能針對每個特定帳號進行精準發文與擷取分析。

後續步驟

如需更多使用者體驗的細節，請參閱：

使用者整合

一旦你的使用者完成社群媒體連結，你就可以透過 /post 與 /profile 端點開始代為發文。

整合流程

建立 Ayrshare 使用者設定檔

透過 API 建立設定檔

Profiles

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

在儀表板中管理使用者設定檔

整合套件

使用 JWT 驗證進行單一登入

產生 JWT

白牌連結帳號頁面

白牌連結帳號頁面

自動登出設定檔工作階段

開啟與關閉社群連結 URL

開啟社群連結 URL

關閉時重新導向

更多資訊

使用者連結／取消連結通知

多組社群帳號

概觀

範例

後續步驟

使用者整合

Post API

Profiles API

​整合流程

​建立 Ayrshare 使用者設定檔

​透過 API 建立設定檔

Profiles

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

在儀表板中管理使用者設定檔

​整合套件

​使用 JWT 驗證進行單一登入

​產生 JWT

​白牌連結帳號頁面

白牌連結帳號頁面

​自動登出設定檔工作階段

​開啟與關閉社群連結 URL

​開啟社群連結 URL

​關閉時重新導向

​更多資訊

​使用者連結／取消連結通知

​多組社群帳號

​概觀

​範例

​後續步驟

使用者整合

Post API

Profiles API

整合流程

建立 Ayrshare 使用者設定檔

透過 API 建立設定檔

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

整合套件

使用 JWT 驗證進行單一登入

產生 JWT

白牌連結帳號頁面

自動登出設定檔工作階段

開啟與關閉社群連結 URL

開啟社群連結 URL

關閉時重新導向

更多資訊

使用者連結／取消連結通知

多組社群帳號

概觀

範例

後續步驟