Bauen Sie Ihr eigenes Verknüpfungs-Popup

Direct Mode verbindet ein soziales Netzwerk nach dem anderen, über eine Schaltfläche in Ihrem eigenen Dashboard. Sie erstellen eine Link Session für dieses Netzwerk, öffnen die zurückgegebene URL in einem Popup, und Ihre Seite erfährt, was passiert ist. Ihr Nutzer sieht nie eine Seite, die alle Netzwerke auflistet, und verlässt Ihre App nie länger, als das Login des Netzwerks selbst dauert.

Welche Oberfläche Sie möchten

Drei Varianten, und die ersten beiden sind dieselbe Integration. Diese Seite ist die, die Sie selbst bauen.

Oberfläche	Ihr Nutzer sieht	White-Labeling	Wählen Sie sie, wenn
Widget — eingebettete Frames (mount)	unsere Schaltflächen inline in Ihrem eigenen Layout; kein Popup bis zu dem des Netzwerks	Am stärksten. Ihre Seite, Ihre Schriften und Farben, und Ihr Nutzer verlässt sie nie	Sie haben ein Dashboard mit einer Zeile pro Netzwerk und möchten, dass die Verknüpfung an Ort und Stelle geschieht. Max Pack.
Widget — Ihre eigene Schaltfläche (popup)	Ihre Schaltfläche, dann ein Popup für das Netzwerk	Stark. Das Popup ist unseres, aber es ist kurz und übernimmt Ihr Erscheinungsbild	Sie möchten Ihre eigene Schaltfläche und Ihr eigenes Styling, und keine Frames in Ihrem Layout. Max Pack.
Gehostete Verknüpfungsseite (Anleitung)	eine von uns gehostete Seite mit Ihrem Logo, Ihren Farben und eigenem CSS	Am schwächsten. Es ist unsere Seite, und Ihr Nutzer verlässt Ihre, um sie zu nutzen	Sie möchten einen Link zum Weitergeben, oder Sie onboarden per E-Mail. Nichts zu bauen, kein Max Pack.

Direct Mode ist das Popup der zweiten Zeile ohne unser Skript. Wenn Ihre Seite das Skript laden kann, erledigt das Widget alles auf dieser Seite für Sie — es öffnet und überwacht das Popup selbst und kann außerdem Frames einbetten. Direct Mode ist das Richtige, wenn Ihre Seite kein Drittanbieter-Skript laden kann oder die Oberfläche eine native App statt eines Browsers ist.

Was Sie bauen

Vier Schritte. Der erste läuft auf Ihrem Server, der Rest in Ihrer Seite.

Erstellen Sie eine Session für ein Netzwerk

Rufen Sie aus Ihrem Backend Eine Link Session erstellen mit mode: "connect", dem network und der origin auf, auf der Ihre Seite läuft.

Your backend

const response = await fetch("https://api.ayrshare.com/api/profiles/link-sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.AYRSHARE_API_KEY}`,
    "Profile-Key": profileKey,
  },
  body: JSON.stringify({
    mode: "connect",
    network: "reddit",
    origin: "https://app.example.com",
  }),
});

const { url } = await response.json();

Sie erhalten eine url zurück, die auf eine Connect-Seite für ein einzelnes Netzwerk zeigt, und kein token — das Token steckt in der URL. Behandeln Sie die gesamte URL wie ein Passwort: Sie meldet Ihren Nutzer in seinem User Profile an.

Erstellen Sie die Session auf Ihrem Server, nie im Browser. Der Aufruf benötigt Ihren API Key.

Öffnen Sie sie im Click-Handler, synchron

Das Popup muss von window.open im Click-Handler selbst geöffnet werden. Ein Browser erlaubt ein Popup nur, solange er den Klick Ihres Nutzers noch verarbeitet, und diese Erlaubnis überlebt kein await — die URL erst zu laden und im Callback zu öffnen, wird also zuverlässig vom Popup-Blocker gestoppt.Laden Sie die URL, wenn Sie die Schaltfläche rendern, oder wenn Ihr Nutzer darüber hovert. Zum Zeitpunkt des Klicks sollten Sie sie bereits haben.

Your page

// `url` was fetched earlier. Nothing async between the click and window.open.
button.addEventListener("click", () => {
  const popup = window.open(url, "ayrshare-connect", "width=600,height=800");
  if (!popup) {
    showError("Allow popups for this site to connect an account.");
    return;
  }
  listenForOutcome(popup, url);
});

Warten Sie auf das Ergebnis

Weil Sie origin übergeben haben, sendet das Popup für alles, was darin passiert, ein Event an Ihre Seite: connect:success, connect:error, connect:cancelled und dazwischen Fortschritts-Events. Genau eines dieser drei kommt pro Verbindung an.Link-Completion-Events enthält die vollständige Event-Tabelle und einen Listener zum Kopieren — listenForOutcome oben ist genau dieses Snippet. Zwei Teile davon werden leicht vergessen, und beide verursachen echte Bugs:

Prüfen Sie event.origin gegen die Origin der URL, die Sie geöffnet haben. Jede Seite kann eine Message an Ihr Fenster senden, und die Origin ist der einzige Teil einer Message, der nicht gefälscht werden kann.
Pollen Sie popup.closed, mit einem kurzen Puffer, bevor Sie einen Schluss ziehen. Ein von Ihrem Nutzer von Hand geschlossenes Popup sendet gar nichts, und ohne den Puffer kann eine erfolgreiche Verbindung als abgebrochen gemeldet werden.

Behandeln Sie jede Endung

Endung	Bedeutung	Was zu tun ist
`connect:success`	das Konto ist verbunden und gespeichert	aktualisieren Sie diese Zeile. Ein `GET /user` direkt danach zeigt es bereits.
`connect:error`	die Verbindung ist fehlgeschlagen	zeigen Sie `message` an. `code` ist vorhanden, wenn der Fehler einen katalogisierten Code hat, und fehlt, wenn nicht.
`connect:cancelled`	Ihr Nutzer hat abgebrochen oder das Fenster geschlossen	lassen Sie die Zeile, wie sie war. `reason` ist `popupClosed`, `scopesDenied` oder `userCancelled`.
nichts kommt an	der Link war abgelaufen, widerrufen oder unbekannt, die Seite hat also nie erfahren, wohin Events zu senden sind	pollen Sie Eine Link Session abrufen, das diese Zustände verbindlich meldet.

Hängen Sie während der Entwicklung &autoClose=false an die URL an. Das Popup bleibt dann nach jedem Ergebnis geöffnet, statt sich zu schließen, sodass Sie lesen können, was es anzeigt.

Hinweise pro Netzwerk

Die meisten Netzwerke sind ein Popup und sonst nichts: Ihr Nutzer klickt, autorisiert beim Netzwerk, und das Popup schließt sich. Dies sind die Ausnahmen, die Sie vor dem Bauen kennen sollten.

X erfordert Ihre eigenen API Keys

X in Direct Mode verwendet Ihre Zugangsdaten Ihrer X Developer App, übergeben beim Erstellen der Session als Header X-Twitter-OAuth1-Api-Key und X-Twitter-OAuth1-Api-Secret auf Eine Link Session erstellen.Eine für twitter oder x ohne diese Header erstellte Session wird beim Öffnen des Popups verweigert: Ihrem Nutzer wird mitgeteilt, dass die Verbindung nicht verfügbar ist, ohne Formular, und Ihre Seite erhält connect:error mit einer message und ohne code. Das ist beabsichtigt. Die fehlenden Zugangsdaten sind Ihre, nicht die Ihres Nutzers, und Endnutzer dürfen nie aufgefordert werden, Ihre API Keys einzugeben.Anders bei Bluesky, wo das App-Passwort die eigene Zugangsinformation des Endnutzers ist — dieses sammelt die Connect-Seite sehr wohl ein, in einem Formular im Popup.

network: "facebook" zeigt eine einzelne Schaltfläche im Popup, und Metas eigenes Login öffnet sich aus diesem Klick — Meta verlangt, dass sein Login durch einen Klick innerhalb der Seite gestartet wird, die sein SDK hostet. Ihr Nutzer klickt zweimal statt einmal; sonst ändert sich nichts.Instagram verhält sich genauso, wenn es über eine Facebook-Seite verknüpft wird — also wenn die Session instagramLinkMethod: "facebook" trägt oder die Instagram-Login-Einstellung Ihres Accounts diesen Ablauf wählt. Beim direkten Instagram Login gibt es keine zusätzliche Schaltfläche.

Bluesky und Telegram zeigen Seiteninhalt, keine Weiterleitung

Keines der beiden schickt Ihren Nutzer zu einem Netzwerk-Login. Das Popup rendert stattdessen Inhalt: ein Handle- und App-Passwort-Formular für Bluesky und einen Code zur Verwendung für Telegram. Die Ergebnis-Events sind in beiden Fällen dieselben.X gehört nicht in diese Gruppe. Mit Ihren Keys auf der Session schließt es ab, ohne Ihren Nutzer nach irgendetwas zu fragen, und ohne sie wird es verweigert — siehe oben.

Telegram schließt außerhalb des Browsers ab

Telegram zeigt einen Code, statt irgendwohin weiterzuleiten, und die Verbindung wird abgeschlossen, wenn Ihr Nutzer diesen Code verwendet — nachdem das Popup weg ist. Es gibt kein Browser-Event, auf das gewartet werden könnte, pollen Sie also Eine Link Session abrufen und beobachten Sie completedNetworks.

Facebook Groups lassen sich auf diesem Weg nicht verbinden

Facebook Groups ist kein Verknüpfungsziel, network: "fbg" gibt also beim Erstellen der Session code: 508 zurück.WhatsApp ist in Direct Mode verfügbar. Es öffnet Metas Embedded Signup im Popup, und die Ergebnis-Events sind dieselben wie bei jedem anderen Netzwerk.

Native Apps

Eine native App öffnet dieselbe url, im Systembrowser, und erfährt das Ergebnis durch Pollen von Eine Link Session abrufen. Setzen Sie origin auf Ihr eigenes Custom Scheme (myapp://connected), damit die Seite einen Rückweg in Ihre App hat; ein Custom Scheme kann keine Events empfangen, weil es kein Browserfenster gibt, an das sie gesendet werden könnten.

iOS — ASWebAuthenticationSession oder SFSafariViewController.
Android — Chrome Custom Tabs.

Öffnen Sie eine Linking-URL nie in einer eingebetteten WebView (WKWebView, UIWebView, Android WebView). Die sozialen Netzwerke verweigern darin die Authentifizierung: Google lehnt die Anmeldung mit disallowed_useragent ab, und Meta blockiert sie vollständig. Ihr Nutzer sieht die Fehlerseite des Netzwerks, nicht unsere, und nichts, was Sie auf Ihrer Seite ändern können, behebt das. Die oben genannten Systembrowser-Komponenten existieren genau aus diesem Grund und halten den Nutzer in Ihrer App.

Was Direct Mode erfordert

Der Max Pack. Das Erstellen einer Connect-Mode-Session ohne ihn gibt code: 504 zurück, was auch immer der Rest der Anfrage sagt.
Ein origin auf jeder Session. Es gibt keine Allowlist und keinen Registrierungsschritt — Sie senden ihn pro Aufruf. Weglassen gibt code: 505 zurück; ein Wert, der keine https-Origin, kein Custom Scheme und nicht http://localhost ist, gibt code: 506 zurück.
Ein network, das Ihr Account aktiviert hat. Ein unbekannter Name gibt code: 508 zurück; ein bekannter, den Ihr Account nicht aktiviert hat, gibt code: 509 zurück — das können Sie auf Ihrer Seite Soziale Netzwerke beheben.
Kein allowedSocial. Es kann nicht mit network kombiniert werden (code: 507) — eine Session für ein einzelnes Netzwerk ist bereits ihre eigene Allowlist.

Jeder dieser Codes steht in der Referenz Link-Session-Fehler, mit der Meldung, die die API zurückgibt.

Nächste Schritte

Link-Completion-Events

Jedes Event, das das Popup sendet, und der Listener, um sie zu empfangen.

Eine Link Session erstellen

Die Parameter mode, origin und network sowie die Antwortformen.

Eine Link Session abrufen

Pollen Sie auf Abschluss, wenn Sie kein Popup verwenden können.

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Welche Oberfläche Sie möchten

Was Sie bauen

Hinweise pro Netzwerk

Native Apps

Was Direct Mode erfordert

Nächste Schritte

Link-Completion-Events

Verwandte Themen

Eine Link Session erstellen

Eine Link Session abrufen

​Welche Oberfläche Sie möchten

​Was Sie bauen

​Hinweise pro Netzwerk

​Native Apps

​Was Direct Mode erfordert

​Nächste Schritte

Link-Completion-Events

​Verwandte Themen

Eine Link Session erstellen

Eine Link Session abrufen

Welche Oberfläche Sie möchten

Was Sie bauen

Hinweise pro Netzwerk

Native Apps

Was Direct Mode erfordert

Nächste Schritte

Verwandte Themen