どのサーフェスを使うべきか
形は 3 つあり、最初の 2 つは同じ統合です。このページは、貴社が自分で構築するものです。ダイレクトモードは、当社のスクリプトなしで実現する 3 行目のポップアップです。 ページが
スクリプトを読み込めるなら、ウィジェットがこのページの内容を
すべて代わりに行います — ポップアップを自分で開いて監視し、さらにフレームの埋め込みもできます。
ダイレクトモードは、ページがサードパーティのスクリプトを読み込めない場合や、サーフェスがブラウザ
ではなくネイティブアプリの場合に選ぶものです。

貴社のボタン、貴社のページ。ユーザーが目にする当社のものはポップアップだけで、それもネットワークが必要とする間だけです。
構築するもの
ステップは 4 つです。最初の 1 つはサーバー上で、残りはページ内で行います。1
1 つのネットワーク用のセッションを作成する
バックエンドから、単一ネットワークの connect ページを指す
mode: "connect"、network、そして貴社のページが動作する origin を指定して
Link Session の作成を呼び出します。Your backend
url が返され、token は返されません — トークンは
URL の中にあります。URL 全体をパスワードと同様に扱ってください: ユーザーを User Profile に
サインインさせるものです。2
クリックハンドラー内で同期的に開く
ポップアップは、クリックハンドラーそのものの中で
window.open によって開く必要があります。
ブラウザは、ユーザーのクリックを処理している間しかポップアップを許可せず、その許可は await を
越えて存続しません — そのため、URL を先に fetch してコールバックで開く方法は、確実にポップアップ
ブロックに引っかかります。URL はボタンをレンダリングするとき、またはユーザーがホバーしたときに fetch してください。クリック
の時点では、すでに手元にあるはずです。Your page
3
結果をリッスンする
origin を渡したため、ポップアップは中で起きたことをイベントとして貴社のページに post します:
connect:success、connect:error、connect:cancelled、およびその間の進捗イベントです。
接続ごとに、この 3 つのうちちょうど 1 つが届きます。リンク完了イベントに完全なイベント一覧とコピー&ペースト
できるリスナーがあります — 上記の listenForOutcome はそのスニペットです。抜けやすい部分が
2 つあり、どちらも実際のバグの原因になります:event.originをチェックする — 開いた URL のオリジンと照合します。どのページでも貴社の ウィンドウにメッセージを post でき、偽装できないのはメッセージのうちオリジンだけです。popup.closedをポーリングする — 何かを結論づける前に短い猶予時間を置いてください。 ユーザーが手動で閉じたポップアップは何も送信せず、猶予時間がないと成功した接続が キャンセルとして報告されることがあります。
4
それぞれの結末を処理する
ネットワーク別の注意点
ほとんどのネットワークは、ポップアップ 1 つでそれ以外に何もありません: ユーザーがクリックし、 ネットワーク側で認可すると、ポップアップが閉じます。構築前に知っておく価値がある例外は以下のとおり です。X には貴社自身の API キーが必要
X には貴社自身の API キーが必要
ダイレクトモードの X は、貴社の X Developer App の認証情報を使用します。セッション作成時に
Link Session の作成の
X-Twitter-OAuth1-Api-Key および
X-Twitter-OAuth1-Api-Secret ヘッダーとして指定します。これらのヘッダーなしで twitter または x 向けに作成されたセッションは、ポップアップが
開いた時点で拒否されます: ユーザーには接続を利用できない旨が表示されてフォームは表示されず、
貴社のページは message 付きで code のない connect:error を受け取ります。これは意図的な
ものです。欠けている認証情報はユーザーのものではなく貴社のものであり、エンドユーザーに貴社の
API キーの入力を求めてはならないからです。対照的なのが Bluesky で、アプリパスワードはエンドユーザー自身の認証情報です — こちらは connect
ページがポップアップ内のフォームで収集します。Facebook は Meta のログインの前にボタンを 1 つ表示する
Facebook は Meta のログインの前にボタンを 1 つ表示する
network: "facebook" はポップアップ内にボタンを 1 つ表示し、そのクリックから Meta 自身の
ログインが開きます — Meta は、その SDK をホストするページ内のクリックからログインが開始される
ことを要求しています。ユーザーのクリックは 1 回ではなく 2 回になりますが、それ以外に違いは
ありません。Instagram を Facebook Page 経由でリンクする場合 — つまりセッションが
instagramLinkMethod: "facebook" を持つ場合や、アカウントの
Instagram Login 設定がそのフローを選択
している場合 — も同じ挙動になります。直接の Instagram Login では追加のボタンはありません。Bluesky と Telegram はリダイレクトではなくページコンテンツを表示する
Bluesky と Telegram はリダイレクトではなくページコンテンツを表示する
どちらもユーザーをネットワークのログインに送りません。代わりにポップアップがコンテンツを
レンダリングします: Bluesky はハンドルとアプリパスワードのフォーム、Telegram は使用するコード
です。結果のイベントはどちらの場合も同じです。X はこのグループには入りません。セッションに貴社のキーがあればユーザーに何も求めずに完了し、
なければ拒否されます — 上記を参照してください。
Telegram は帯域外で完了する
Telegram は帯域外で完了する
Telegram はどこにもリダイレクトせずにコードを表示し、接続はユーザーがそのコードを使用した時点 —
ポップアップが消えた後 — で完了します。待つべきブラウザイベントがないため、
Link Session の取得をポーリングして
completedNetworks を
監視してください。Facebook Groups はこの方法では接続できない
Facebook Groups はこの方法では接続できない
Facebook Groups はリンク対象ではないため、
network: "fbg" はセッション作成時に code: 508 を
返します。WhatsApp はダイレクトモードで利用できます。ポップアップ内で Meta の Embedded Signup が
開き、結果のイベントは他のネットワークと同じです。ネイティブアプリ
ネイティブアプリは同じurl をシステムブラウザで開き、
Link Session の取得をポーリングして結果を知ります。origin には
カスタムスキーム(myapp://connected)を設定し、ページがアプリに戻る手段を確保してください。カスタム
スキームはイベントを受信できません。post する先のブラウザウィンドウが存在しないためです。
- iOS —
ASWebAuthenticationSession、またはSFSafariViewController。 - Android — Chrome Custom Tabs。
ダイレクトモードに必要なもの
- Max Pack。Max Pack なしで connect モードのセッションを作成すると、
リクエストの他の内容にかかわらず
code: 504が返されます。 - すべてのセッションに
origin。ホワイトリストも登録手順もありません — 呼び出しごとに送信 します。省略するとcode: 505が返されます。httpsオリジン、カスタムスキーム、http://localhostのいずれでもない値はcode: 506を返します。 - アカウントで有効になっている
network。認識されない名前はcode: 508を返します。認識 されるがアカウントで有効になっていないものはcode: 509を返し、これは Social Networks ページで 修正できます。 allowedSocialは指定しないこと。networkと組み合わせることはできません(code: 507)— 単一ネットワークのセッションは、それ自体がすでにホワイトリストだからです。
次のステップ
リンク完了イベント
ポップアップが送信するすべてのイベントと、それらを受信するリスナー。
関連情報
Link Session の作成
mode、origin、network パラメータとレスポンスの形。Link Session の取得
ポップアップを使えない場合の、完了のポーリング。