Profile-Key 透過
建立 Link Session 建立。你這一側不需要簽署任何內容,流程中也沒有 private key。唯一的例外是會自行簽署 token 的較早整合。請參閱自行簽署的 token(舊版)。
三種連結方式
三種形態,而前兩種是同一個整合。依流程挑選即可——它們並不互斥,許多整合會在導入階段使用代管頁面,之後在應用程式內改用小工具。兩個小工具列是同一個整合,不是兩個。單一
init 便同時提供兩者:在你想放我們按鈕的位置掛載框架,
並在其他任何地方從你自己的按鈕呼叫 popup()。它們共用同一個工作階段,並在相同的處理常式上回報。直接模式(Direct Mode)是不使用我們指令碼的同一個彈出視窗——
適用於帶有嚴格 Content-Security-Policy 的頁面、伺服器端渲染的頁面,或原生應用程式。在那裡,
你自行開啟並監看彈出視窗。**不確定該選哪個?**先從代管連結頁面開始。它不需要 Max Pack,也不需要額外參數,
是最快看到成果的路徑——之後改用小工具時,建立工作階段的方式並不會改變。建立連結
在標頭中帶上使用者的Profile-Key,呼叫建立 Link Session。
對代管頁面而言,這就是完整的請求:
cURL
url:
Linking URL
這支 1 分鐘影片示範了如何建立連結。它錄製於 link sessions 之前,因此仍會顯示傳送 Private Key
的步驟——該步驟已不再需要,其餘示範內容則沒有改變。
傳送連結 URL
開啟連結 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 帳號可以透過兩種方式連結:直接使用 Instagram Login,或透過已連結的 Facebook 粉絲專頁。當使用者點擊 Instagram 按鈕時會啟動 哪一種流程,通常由帳號層級的 Instagram Login 設定控制。instagramLinkMethod body 參數可針對單一連結覆寫該設定:
Instagram Link Method
- 它不會改變你的帳號層級設定,也不會影響任何其他連結。
- 若省略此欄位,會沿用帳號層級設定,與之前一致。
- 若傳入無效值,將回傳
400並列出有效值(instagram、facebook)。 - 在選擇之前,請先參閱兩種流程的 功能差異 ——部分 Instagram 功能,例如 hashtag 搜尋與 collaborations(協作),僅支援 Facebook 粉絲專頁驗證。
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。這可以保護你的帳戶,但不一定能讓已外洩的連結失效。如需讓該連結失效,請聯絡支援團隊。