Skip to main content
當你在彈出視窗中開啟連結頁面時,你自己的頁面可以監聽裡面發生的事:你的使用者連結了 Reddit、 中途退出、連結失敗。每種結果都會有一個事件,因此你的 UI 會在事情發生的那一刻更新, 而不是靠計時器。 在建立連結時設定 origin,在彈出視窗中開啟回傳的 url,然後監聽即可。不需要任何其他東西,而未帶 origin 建立的連結也沒有任何改變—— 它們的行為與以往完全相同。
正在使用內嵌小工具?這些已經替你接好了。指令碼會接收 這些事件並在去掉 connect: 前綴後交給 connect.on("success", …)——不必寫 message 監聽器、 不必檢查來源、不必輪詢 popup.closed。本頁是底層的線路協定,也是當擁有視窗時所要 依循的內容:直接模式,或你自行開啟的彈出視窗。
事件只會傳送到你在連結上設定的確切 origin,且只傳給開啟彈出視窗的視窗。無論如何, 請一律在監聽器中檢查 event.origin:任何頁面都可以向你的視窗傳送訊息,而來源是訊息中 唯一無法偽造的部分。

事件

傳送到你頁面的每則訊息都是形如 { source: "ayrshare", version: 1, event, ... } 的物件,且只要 事件與某個網路有關就帶有 network。有兩個事件不是:來自代管連結頁面的 connect:closed (它代表使用者按下了 Done,而不是某次連結結束),以及小工具的 connect:ready(見下文)。 由你自己的程式碼合成的結果——被封鎖的彈出視窗,或使用者親手關閉的視窗——不是我們送出的, 只帶有你給它們的內容。
內嵌小工具在一個事件上有所不同。它的 ready 宣告的是某個 插槽已就緒,而非任何與網路有關的事,因此不帶 network——而彈出視窗的 ready 會標明它是為 哪個網路開啟的。如果你用同一個監聽器處理兩種介面,請在 ready 上防禦性地讀取 network小工具還多了一個此介面永遠不會送出的 cancelled reason:superseded,即第二次 popup() 呼叫取代了仍在進行中的嘗試。這裡只有一個視窗與一個結果,所以沒有東西可以被取代。
每次連結恰好送達 connect:successconnect:errorconnect:cancelled 其中之一。 connect:closed 不屬於它們——它在其後送達,告訴你彈出視窗是刻意關閉的。 connect:success 只會在帳號儲存完成後送出,因此緊接其後的 GET /user 已經會顯示已連結的帳號。
彈出視窗在 connect:error 之後會保持開啟,讓你的使用者可以讀取哪裡出了問題。它在 connect:successconnect:cancelled 之後會自行關閉。除錯時可在 URL 加上 &autoClose=false,讓它在任何情況下都保持開啟。

監聽

這段程式碼做了兩件容易漏掉的事。它會檢查 event.origin,並監看使用者親手關閉的彈出視窗—— 已關閉的視窗無法送出任何東西,所以輪詢是唯一能察覺的方式。

錯誤

connect:error 帶有與 API 其他部分相同的錯誤碼,因此你在這裡看到的錯誤碼與它在其他任何地方的 意義相同。專屬於此介面的一個: 其他任何錯誤都是社群網路自身的失敗,並以該失敗原本的錯誤碼回報——例如 Instagram 授權問題的 322,其中包括仍是個人帳號而非專業帳號的情況。

失效的連結以不同的方式呈現

已過期已撤銷不存在的連結會在頁面得知該把事件送到哪裡之前就被拒絕,因此無法送出 任何事件。你的使用者會在畫面上看到原因與其錯誤碼,而你的頁面會在他們關閉視窗時聽到 connect:cancelled 若要區分這三者,請輪詢取得 Link Session:它會權威地回報 expiredrevoked,並對不存在的連結回傳 502

如果你不想管理彈出視窗

兩個選項,且只有第二個會放棄事件。 讓小工具擁有視窗。內嵌小工具會替你開啟並監看它,並將上面的 每個事件送到你的處理常式。帳號一儲存你仍會在那一刻收到 success;只是不必自己寫這些管線。 它的框架也意味著大多數網路在該網路自身的登入之前根本不會開啟任何彈出視窗。 **改為輪詢。**如果真的無法使用彈出視窗——伺服器端渲染的應用程式,或在系統瀏覽器中開啟連結的 行動應用程式——請輪詢取得 Link Session。帳號一儲存它就會回報 completedAtcompletedNetworks,這與 connect:success 原本會送出的時刻相同。Telegram 一律以這種方式完成,因為它在頻外完成,完全沒有瀏覽器回呼。