你需要哪一種介面
三種形態,而前兩種是同一個整合。本頁是你自行建置的那一種。**直接模式是第三列的彈出視窗,但不使用我們的指令碼。**如果你的頁面可以載入指令碼,
小工具會替你完成本頁的所有事情——它會自行開啟並監看彈出視窗,
也能內嵌框架。當你的頁面無法載入第三方指令碼,或介面是原生應用程式而非瀏覽器時,
直接模式才是你需要的。

你的按鈕,你的頁面。彈出視窗是使用者唯一會看到的我們的東西,而且只在網路需要的時間內存在。
你要建置的東西
四個步驟。第一個在你的伺服器上,其餘在你的頁面中。1
為單一網路建立工作階段
從你的後端呼叫
建立 Link Session,帶上 你會取得一個指向單一網路連結頁面的
mode: "connect"、
network,以及你頁面執行所在的 origin。Your backend
url,而且沒有 token——token 就在 URL 裡。請把整個
URL 當成密碼對待:它會讓你的使用者登入他們的 User Profile。2
在點擊處理常式中同步開啟它
彈出視窗必須由
window.open 在點擊處理常式本身之中開啟。瀏覽器只在仍在處理使用者點擊
的期間允許開啟彈出視窗,而這個許可撐不過一個 await——所以先抓取 URL、再在回呼中開啟它,
幾乎一定會被彈出視窗封鎖。在渲染按鈕時、或在使用者滑鼠移到按鈕上時就抓取 URL。到點擊的時候,你手上應該已經有它了。Your page
3
監聽結果
因為你傳了
origin,彈出視窗會把裡面發生的每件事以事件的形式傳給你的頁面:
connect:success、connect:error、connect:cancelled,以及其間的進度事件。每次連結
恰好送達這三者其中之一。連結完成事件有完整的事件表與可直接複製貼上的
監聽器——上面的 listenForOutcome 就是那段程式碼。其中有兩個部分很容易漏掉,且都會造成
真正的 bug:- 檢查
event.origin,與你開啟的 URL 的來源比對。任何頁面都可以向你的視窗傳送訊息, 而來源是訊息中唯一無法偽造的部分。 - 輪詢
popup.closed,並在下結論之前留一小段緩衝時間。使用者親手關閉的彈出視窗什麼 都不會送出,而沒有緩衝時間的話,成功的連結可能被回報為已取消。
4
處理每種結局
各網路注意事項
大多數網路就是一個彈出視窗,別無其他:你的使用者點擊、在該網路授權、彈出視窗關閉。以下是 建置前值得知道的例外情況。X 需要你自己的 API 金鑰
X 需要你自己的 API 金鑰
直接模式中的 X 使用你自己的 X Developer App 憑證,在建立工作階段時以
X-Twitter-OAuth1-Api-Key 與 X-Twitter-OAuth1-Api-Secret 標頭提供給
建立 Link Session。為 twitter 或 x 建立、但沒有這些標頭的工作階段,會在彈出視窗開啟時被拒絕:你的
使用者會被告知此連結不可用且不會看到任何表單,而你的頁面會收到帶 message 且沒有
code 的 connect:error。這是刻意的。缺少的憑證是你的,不是你使用者的,而終端使用者
絕不應被要求輸入你的 API 金鑰。對照 Bluesky:其 app password 是終端使用者自己的憑證——這一項連結頁面確實會收集,
在彈出視窗內的表單中。Facebook 在 Meta 登入之前多顯示一顆按鈕
Facebook 在 Meta 登入之前多顯示一顆按鈕
network: "facebook" 會在彈出視窗中顯示一顆按鈕,Meta 自己的登入從該次點擊開啟——Meta
要求其登入必須由承載其 SDK 的頁面內的點擊啟動。你的使用者要點兩次而不是一次;其餘沒有差別。當 Instagram 透過 Facebook 粉絲專頁連結時——也就是工作階段帶有
instagramLinkMethod: "facebook",或你帳號的
Instagram Login 設定選擇該流程時——
行為相同。使用直接的 Instagram Login 則沒有額外的按鈕。Bluesky 與 Telegram 顯示頁面內容,而非轉址
Bluesky 與 Telegram 顯示頁面內容,而非轉址
兩者都不會把你的使用者送去網路登入。彈出視窗改為渲染內容:Bluesky 是 handle 與
app password 的表單,Telegram 是一組要使用的代碼。無論哪種方式,結果事件都相同。X 不屬於這一組。工作階段帶有你的金鑰時,它不需要向使用者要求任何東西即可完成;沒有金鑰時
則會被拒絕——見上文。
Telegram 在頻外完成
Telegram 在頻外完成
Telegram 顯示一組代碼而不做任何轉址,連結會在你的使用者使用該代碼時完成——那時彈出視窗
已經不在了。沒有可以等待的瀏覽器事件,因此請輪詢
取得 Link Session 並觀察
completedNetworks。Facebook 社團無法以這種方式連結
Facebook 社團無法以這種方式連結
Facebook 社團不是連結目標,因此
network: "fbg" 在建立工作階段時會回傳 code: 508。WhatsApp 可以在直接模式中使用。它會在彈出視窗中開啟 Meta 的 Embedded Signup,
結果事件與其他網路相同。原生應用程式
原生應用程式開啟同樣的url,但在系統瀏覽器中開啟,並透過輪詢
取得 Link Session 得知結果。將 origin 設為你的自訂 scheme
(myapp://connected),讓頁面有辦法返回你的應用程式;自訂 scheme 無法接收事件,
因為沒有可以接收訊息的瀏覽器視窗。
- iOS——
ASWebAuthenticationSession或SFSafariViewController。 - Android——Chrome Custom Tabs。
直接模式的需求
- Max Pack。在沒有 Max Pack 的情況下建立 connect 模式的工作階段
會回傳
code: 504,無論請求的其他內容為何。 - 每個工作階段都要有
origin。沒有允許清單,也沒有註冊步驟——你在每次呼叫時送出它。 省略它會回傳code: 505;不是https來源、自訂 scheme 或http://localhost的值會回傳code: 506。 - 一個你的帳戶已啟用的
network。無法識別的名稱會回傳code: 508;名稱有效但你的帳戶 尚未啟用時會回傳code: 509,你可以在 Social Networks 頁面自行修正。 - 不要帶
allowedSocial。它不能與network併用(code: 507)——單一網路的工作階段 本身就是自己的允許清單。
後續步驟
連結完成事件
彈出視窗送出的每個事件,以及接收它們的監聽器。
相關資訊
建立 Link Session
mode、origin 與 network 參數,以及回應的形態。取得 Link Session
無法使用彈出視窗時,改以輪詢確認完成。