跳轉到主要內容
你的使用者會自行連結他們的社群帳號——他們直接向每個社群網路進行驗證,你永遠不會看到或儲存他們的憑證。本頁的所有內容,都是關於如何讓他們走到那一刻,以及如何得知結果。 所有路徑都有一個共同點:一個 link session,由你的 API Key 與 Profile-Key 透過 建立 Link Session 建立。你這一側不需要簽署任何內容,流程中也沒有 private key。唯一的例外是會自行簽署 token 的較早整合。請參閱自行簽署的 token(舊版)。

三種連結方式

三種形態,而前兩種是同一個整合。依流程挑選即可——它們並不互斥,許多整合會在導入階段使用代管頁面,之後在應用程式內改用小工具。
兩個小工具列是同一個整合,不是兩個。單一 init 便同時提供兩者:在你想放我們按鈕的位置掛載框架, 並在其他任何地方從你自己的按鈕呼叫 popup()。它們共用同一個工作階段,並在相同的處理常式上回報。直接模式(Direct Mode)是不使用我們指令碼的同一個彈出視窗—— 適用於帶有嚴格 Content-Security-Policy 的頁面、伺服器端渲染的頁面,或原生應用程式。在那裡, 你自行開啟並監看彈出視窗。**不確定該選哪個?**先從代管連結頁面開始。它不需要 Max Pack,也不需要額外參數, 是最快看到成果的路徑——之後改用小工具時,建立工作階段的方式並不會改變。

建立連結

在標頭中帶上使用者的 Profile-Key,呼叫建立 Link Session。 對代管頁面而言,這就是完整的請求:
cURL
你會取得一個帶有短效、不透明 token 的 url:
Linking URL
你也可以查看連結是否已被開啟,並在過期前 撤銷它。
這支 1 分鐘影片示範了如何建立連結。它錄製於 link sessions 之前,因此仍會顯示傳送 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 唯一的訊號—— Telegram 的連結在頻外完成。

連結有效期

連結預設有效 5 分鐘。之後請建立新的連結。 搭配 Max Pack,以分鐘為單位設定 expiresIn 即可延長有效期——最長 2880 分鐘(48 小時), 這是 API 接受的上限:
Expires In
較長的有效期正是讓以電子郵件寄送連結變得實際可行的關鍵——需要重新連結 帳號的使用者可以直接從你的電子郵件前往社群網路,而不必先造訪你的應用程式。
請與你的資安團隊確認連結應保持有效多久。較長的有效期,意味著被攔截的連結可用的時間也更長。 如果連結外洩,你可以撤銷它,而不必等它過期。

安全性

工作階段 token 位於連結 URL 的查詢字串中。任何會記錄 URL 的地方都可能記錄下它:使用者的瀏覽器歷史紀錄、Proxy 與伺服器日誌、分析工具,以及轉址服務。 為降低風險:
  • 不要在你自己的系統中記錄完整的 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 Login,或透過已連結的 Facebook 粉絲專頁。當使用者點擊 Instagram 按鈕時會啟動 哪一種流程,通常由帳號層級的 Instagram Login 設定控制。 instagramLinkMethod body 參數可針對單一連結覆寫該設定:
Instagram Link Method
此覆寫在該連結的整個生命週期內都有效,包含跨越 Instagram/Facebook 授權轉址的過程。幾點須知:
  • 它不會改變你的帳號層級設定,也不會影響任何其他連結。
  • 若省略此欄位,會沿用帳號層級設定,與之前一致。
  • 若傳入無效值,將回傳 400 並列出有效值(instagram、facebook)。
  • 在選擇之前,請先參閱兩種流程的 功能差異 ——部分 Instagram 功能,例如 hashtag 搜尋與 collaborations(協作),僅支援 Facebook 粉絲專頁驗證。

Connect Accounts 電子郵件

Ayrshare 可以替你將連結以電子郵件寄給使用者,讓他們不必造訪你的應用程式即可前往連結頁面。 請搭配較長的 expiresIn 使用——預設的 5 分鐘通常撐不過收件匣。

Connect Accounts JSON

**email 內的每個欄位都是必填。**缺少任何一個都會導致寄送失敗。
Example Contact Email Request
expiresIn 是頂層參數,不屬於 email 物件。若巢狀放在 email 內會被忽略, 你的使用者會拿到一個 5 分鐘後就過期的連結。
回應會在 emailSent 中回報寄送結果:
Example Contact Email Response
如果無法寄送電子郵件,請求仍會成功,你仍然會取得連結。回應會包含 emailSent: false 與一個 emailError 物件,讓你可以透過其他方式將連結交給使用者:
Example Failed Email Response
只要你請求寄送電子郵件但郵件沒有寄出,就會出現 emailError:可能是寄送失敗,或是 email 物件缺少必填欄位(此時 details 會列出缺少的欄位)。emailSent: false 但沒有 emailError 代表沒有請求寄送電子郵件。缺少 to 則不同:整個請求會被拒絕,並回傳 code: 188。

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。

自行簽署的 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。這可以保護你的帳戶,但不一定能讓已外洩的連結失效。如需讓該連結失效,請聯絡支援團隊。