Skip to main content
ダイレクトモード(Direct Mode)は、貴社自身のダッシュボードのボタンから、ソーシャルネットワークを 一度に 1 つ連携します。そのネットワーク用のリンクセッションを作成し、返された URL をポップアップで 開くと、何が起きたかを貴社のページが受け取ります。ユーザーがすべてのネットワークを列挙したページを 目にすることはなく、貴社のアプリを離れる時間はネットワーク自身のログインにかかる時間だけです。

どのサーフェスを使うべきか

形は 3 つあり、最初の 2 つは同じ統合です。このページは、貴社が自分で構築するものです。
ダイレクトモードは、当社のスクリプトなしで実現する 3 行目のポップアップです。 ページが スクリプトを読み込めるなら、ウィジェットがこのページの内容を すべて代わりに行います — ポップアップを自分で開いて監視し、さらにフレームの埋め込みもできます。 ダイレクトモードは、ページがサードパーティのスクリプトを読み込めない場合や、サーフェスがブラウザ ではなくネイティブアプリの場合に選ぶものです。
A customer dashboard with its own Connect buttons and an Ayrshare popup showing the Facebook hand-off screen

貴社のボタン、貴社のページ。ユーザーが目にする当社のものはポップアップだけで、それもネットワークが必要とする間だけです。

構築するもの

ステップは 4 つです。最初の 1 つはサーバー上で、残りはページ内で行います。
1

1 つのネットワーク用のセッションを作成する

バックエンドから、mode: "connect"network、そして貴社のページが動作する origin を指定して Link Session の作成を呼び出します。
Your backend
単一ネットワークの connect ページを指す url が返され、token は返されません — トークンは URL の中にあります。URL 全体をパスワードと同様に扱ってください: ユーザーを User Profile に サインインさせるものです。
セッションは必ずサーバー上で作成し、ブラウザ内では作成しないでください。この呼び出しには API Key が必要です。
2

クリックハンドラー内で同期的に開く

ポップアップは、クリックハンドラーそのものの中で window.open によって開く必要があります。 ブラウザは、ユーザーのクリックを処理している間しかポップアップを許可せず、その許可は await を 越えて存続しません — そのため、URL を先に fetch してコールバックで開く方法は、確実にポップアップ ブロックに引っかかります。URL はボタンをレンダリングするとき、またはユーザーがホバーしたときに fetch してください。クリック の時点では、すでに手元にあるはずです。
Your page
3

結果をリッスンする

origin を渡したため、ポップアップは中で起きたことをイベントとして貴社のページに post します: connect:successconnect:errorconnect:cancelled、およびその間の進捗イベントです。 接続ごとに、この 3 つのうちちょうど 1 つが届きます。リンク完了イベントに完全なイベント一覧とコピー&ペースト できるリスナーがあります — 上記の listenForOutcome はそのスニペットです。抜けやすい部分が 2 つあり、どちらも実際のバグの原因になります:
  • event.origin をチェックする — 開いた URL のオリジンと照合します。どのページでも貴社の ウィンドウにメッセージを post でき、偽装できないのはメッセージのうちオリジンだけです。
  • popup.closed をポーリングする — 何かを結論づける前に短い猶予時間を置いてください。 ユーザーが手動で閉じたポップアップは何も送信せず、猶予時間がないと成功した接続が キャンセルとして報告されることがあります。
4

それぞれの結末を処理する

構築中は URL に &autoClose=false を追加してください。ポップアップはどの結末の後も自動的に 閉じずに開いたままになるので、表示内容を読むことができます。

ネットワーク別の注意点

ほとんどのネットワークは、ポップアップ 1 つでそれ以外に何もありません: ユーザーがクリックし、 ネットワーク側で認可すると、ポップアップが閉じます。構築前に知っておく価値がある例外は以下のとおり です。
ダイレクトモードの 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 ページがポップアップ内のフォームで収集します。
network: "facebook" はポップアップ内にボタンを 1 つ表示し、そのクリックから Meta 自身の ログインが開きます — Meta は、その SDK をホストするページ内のクリックからログインが開始される ことを要求しています。ユーザーのクリックは 1 回ではなく 2 回になりますが、それ以外に違いは ありません。Instagram を Facebook Page 経由でリンクする場合 — つまりセッションが instagramLinkMethod: "facebook" を持つ場合や、アカウントの Instagram Login 設定がそのフローを選択 している場合 — も同じ挙動になります。直接の Instagram Login では追加のボタンはありません。
どちらもユーザーをネットワークのログインに送りません。代わりにポップアップがコンテンツを レンダリングします: Bluesky はハンドルとアプリパスワードのフォーム、Telegram は使用するコード です。結果のイベントはどちらの場合も同じです。X はこのグループには入りません。セッションに貴社のキーがあればユーザーに何も求めずに完了し、 なければ拒否されます — 上記を参照してください。
Telegram はどこにもリダイレクトせずにコードを表示し、接続はユーザーがそのコードを使用した時点 — ポップアップが消えた後 — で完了します。待つべきブラウザイベントがないため、 Link Session の取得をポーリングして completedNetworks を 監視してください。
Facebook Groups はリンク対象ではないため、network: "fbg" はセッション作成時に code: 508 を 返します。WhatsApp はダイレクトモードで利用できます。ポップアップ内で Meta の Embedded Signup が 開き、結果のイベントは他のネットワークと同じです。

ネイティブアプリ

ネイティブアプリは同じ urlシステムブラウザで開き、 Link Session の取得をポーリングして結果を知ります。origin には カスタムスキーム(myapp://connected)を設定し、ページがアプリに戻る手段を確保してください。カスタム スキームはイベントを受信できません。post する先のブラウザウィンドウが存在しないためです。
  • iOSASWebAuthenticationSession、または SFSafariViewController
  • Android — Chrome Custom Tabs。
リンク用 URL を埋め込み webview(WKWebViewUIWebView、Android の WebView)で開いては いけません。 ソーシャルネットワークは webview 内での認証を拒否します: Google はサインインを disallowed_useragent で拒否し、Meta は完全にブロックします。ユーザーには当社のものではなく ネットワーク自身のエラーページが表示され、貴社側で変更できるものでは解決できません。上記の システムブラウザコンポーネントはまさにこの理由のために存在し、ユーザーをアプリ内に留めます。

ダイレクトモードに必要なもの

  • 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)— 単一ネットワークのセッションは、それ自体がすでにホワイトリストだからです。
これらはすべて、API が返すメッセージとともに Link Session エラーリファレンスに記載されています。

次のステップ

リンク完了イベント

ポップアップが送信するすべてのイベントと、それらを受信するリスナー。

関連情報

Link Session の作成

modeoriginnetwork パラメータとレスポンスの形。

Link Session の取得

ポップアップを使えない場合の、完了のポーリング。