Skip to main content
Das Ayrshare Connect Widget bringt unsere Verknüpfungs-Schaltflächen in Ihr eigenes Dashboard. Sie laden ein Skript, platzieren einen Slot dort, wo ein Netzwerk in Ihr Layout gehört, und wir rendern dort eine Schaltfläche, die bereits anzeigt, ob das Konto verbunden ist. Ihr Nutzer klickt darauf und verknüpft das Konto, ohne Ihre Seite zu verlassen — höchstens ein Popup, das des Netzwerks selbst. Sie schreiben keine Popup-Behandlung, keine OAuth-Callbacks, keinen Session-Refresh und keine Logik pro Netzwerk. Wenn ein Netzwerk auf seiner Seite etwas ändert, wird die Korrektur in unseren Frames ausgeliefert, sobald wir sie deployen; Sie deployen nichts neu.

Welche Oberfläche Sie möchten

Ein Kunden-Dashboard mit Ayrshare-Connect-Kacheln für Instagram, TikTok und LinkedIn, eingebettet in eine Karte

Eingebettete Frames: unsere Kacheln, gerendert innerhalb Ihres eigenen Layouts, ein Slot pro Netzwerk oder ein Slot für mehrere.

Ein Kunden-Dashboard mit eigenen Connect-Schaltflächen und einem Ayrshare-Popup mit dem Facebook-Übergabebildschirm

Ihre eigene Schaltfläche: Sie rendern die Schaltfläche, und ein kurzes Popup von uns übernimmt das Netzwerk.

Die gehostete Social-Verknüpfungsseite mit allen verfügbaren Netzwerken

Gehostete Verknüpfungsseite: eine von uns gehostete Seite mit Ihrem Logo und Ihren Farben, für die Ihr Nutzer Ihre App verlässt.

Die beiden Widget-Zeilen sind eine Integration, nicht zwei. Ein einziges init gibt Ihnen beides: Mounten Sie Frames dort, wo Sie unsere Schaltflächen möchten, und rufen Sie überall sonst popup() aus Ihrer eigenen Schaltfläche auf. Beide teilen sich eine Session und melden sich über dieselben Handler.Direct Mode ist dasselbe Popup ohne unser Skript — für eine Seite mit strikter Content-Security-Policy, eine servergerenderte Seite oder eine native App. Dort öffnen und überwachen Sie das Popup selbst.

Das Skript einbinden

Pinnen Sie eine Version samt Hash, oder folgen Sie einem Channel ohne Hash. Nie beides — ein integrity-Attribut auf einer beweglichen URL funktioniert ab unserem nächsten Release nicht mehr, weil sich die Datei dahinter legitim geändert hat.
Pinned version
Tracking v1
v1 ist der empfohlene Channel. Er nimmt Korrekturen mit, überschreitet aber nie einen Breaking Change. latest überschreitet per Definition Major-Versionen und liefert Ihrer Seite daher irgendwann eine Version, deren Verhalten Sie nicht geprüft haben. Der Hash jeder Version wird in manifest.json veröffentlicht, die auch benennt, was jeder Channel aktuell ausliefert:
manifest.json
Jedes Bundle beginnt außerdem mit einem Kommentar, der seine eigene Version benennt — der schnellste Weg, uns mitzuteilen, was eine Seite tatsächlich ausführt:

Content-Security-Policy

Wenn Ihre Seite eine Content-Security-Policy sendet, braucht sie zwei Einträge, beide mit dem Host, von dem Sie das Skript laden:
Das ist die vollständige Liste. Sie brauchen keinen connect-src-Eintrag für uns — unsere Frames erreichen unsere API aus sich selbst heraus, nicht von Ihrer Seite aus — und keinen Eintrag für Popups, die als Top-Level-Fenster nicht Ihrer Policy unterliegen. Beide Einträge wurden gemessen: Ohne script-src wird das Skript blockiert, ohne frame-src der Frame.

Eine Instanz starten

session ist die einzige erforderliche Option. Sie wird einmal pro Instanz aufgerufen, nicht einmal pro Mount, und muss die Antwort Ihres Backends auf Eine Link Session erstellen mit mode: "connect" zurückgeben — { sessionId, token, expiresAt } — genau so, wie sie zurückkam.
Your page
Your backend
Eine Widget-Session benennt kein network — sie autorisiert jedes Netzwerk, das Ihr Account erlaubt, und welche erscheinen, wird pro Mount entschieden, in Ihrer Seite. Sie trägt aber ein origin, das Einzige, was die Frames überhaupt rendern lässt: Ein Frame prüft die Seite, die ihn einbettet, gegen diesen Wert und verweigert das Rendern überall sonst.
Erstellen Sie die Session auf Ihrem Server. Der Aufruf benötigt Ihren API Key, und das zurückgegebene Token meldet Ihren Nutzer in seinem User Profile an — behandeln Sie es wie ein Passwort.
Wir rufen session erneut auf, bevor das Token abläuft, sodass das Widget auf einer den ganzen Tag geöffneten Seite weiterarbeitet. Ein Aufruf, der fehlschlägt oder kein Token zurückgibt, wird noch zweimal wiederholt — nach 0,5 s, dann 1 s —, bevor wir aufgeben und error auslösen. Ein Refresh kostet also höchstens drei Aufrufe Ihres Endpunkts.

Einen Slot mounten

Ein mount pro Slot. Fordern Sie ein Netzwerk an, mehrere oder alles, was die Session erlaubt — die Granularität bestimmen Sie, ein Slot kann also eine einzelne Zeile in einer bestehenden Tabelle sein oder ein Panel, das alles enthält.
mount nimmt einen CSS-Selektor oder ein Element entgegen und gibt { unmount, element } zurück. Es wirft eine Exception, wenn das Ziel nichts trifft — fast immer ein Slot, der noch nicht existiert. Mounten Sie also, nachdem Ihr Markup im Dokument ist. Jeder Mount ist ein iframe. Er meldet uns seine eigene Höhe, und wir passen ihn entsprechend an, sodass Ihr Layout mit unseren Inhaltsänderungen umbricht; jenseits von maxHeight scrollt der Frame intern, statt aus Ihrer Seite zu laufen. Der schmalste unterstützte Slot ist 300px. Die Netzwerk-Keys sind Ayrshares eigene, und die Alias-Schreibweisen funktionieren ebenfalls: instagram und instagramapi bedeuten beide instagramApi, und x bedeutet twitter. Ein Key, der kein Netzwerk ist, rendert keine Kachel.

Ihre eigene Schaltfläche

Ein Kunde, der lieber seine eigene Schaltfläche statt eines unserer Frames verwendet, ruft stattdessen popup auf. Es führt denselben Ablauf aus, auf derselben Session, und meldet sich über dieselben Handler.
Rufen Sie es direkt im Click-Handler auf, ohne dass davor etwas awaited wird. Ein Browser erlaubt ein Popup nur, solange er den Klick Ihres Nutzers noch verarbeitet, und diese Erlaubnis überlebt kein await. Es muss ohnehin nichts awaited werden — die Session wurde bei init erstellt.
popup gibt { close(), network } zurück und gibt immer ein Handle zurück — auch nach einem blockierten Popup, wo close() nichts tut —, sodass Ihr Code es vor einem close()-Aufruf nie auf null prüfen muss. Jedes Netzwerk funktioniert hier, auch die, die ein Frame in seinem eigenen Panel abschließt: Facebook zeigt seinen Übergabe-Hinweis im Popup, Bluesky und X zeigen ihr Zugangsdaten-Formular, und LinkedIn, Pinterest, YouTube und Google Business gehen zum Netzwerk hinaus und kommen zurück. Es wirft synchron eine Exception für die drei Dinge, die Programmierfehler sind — kein network, eine zerstörte Instanz oder eine Session, die noch nicht aufgelöst ist. Ein blockiertes Popup gehört nicht dazu: Das löst error mit reason: "popupBlocked" aus, denn Ihr Nutzer hat nichts falsch gemacht. Es ist höchstens ein Popup gleichzeitig geöffnet. Ein zweiter Aufruf schließt das erste und meldet darauf cancelled mit reason: "superseded". Ein Popup, das einer unserer Frames geöffnet hat, ist etwas anderes und wird nie angetastet — Ihre Schaltfläche kann also keinen Ablauf abbrechen, der in einem gemounteten Slot läuft.
Ob die Session ein Netzwerk verknüpfen darf, beantwortet der Server, nicht das Skript. Eine auf Bluesky beschränkte Session, die nach LinkedIn gefragt wird, erhält eine im Popup gerenderte Ablehnung, die als error gemeldet wird. Das Skript prüft nur, dass überhaupt ein Netzwerk benannt wurde.

React

Das Skript ist Framework-frei, React braucht also nichts Besonderes von uns — aber vier Dinge an seinem Lebenszyklus sollten Sie beim ersten Mal richtig machen. Laden Sie das Skript einmal, außerhalb Ihres Komponentenbaums. In Next.js ist das next/script in Ihrem Root-Layout; in Vite oder Create React App ein Tag in index.html. Es pro Komponente zu laden führt es bei jedem Mount erneut aus.
ConnectAccounts.jsx
Verwenden Sie eine Instanz nach destroy() nie wieder. Eine zerstörte Instanz bleibt zerstört — popup() wirft darauf eine Exception, und mount() bringt sie nicht zurück. Erstellen Sie im nächsten Effect-Durchlauf eine neue Instanz, genau wie der Code oben.
Zwei Konsequenzen dieses Musters, beide keine Bugs:
  • In der Entwicklung sehen Sie den Session-Callback zweimal feuern. Reacts Strict Mode führt Effects mount → unmount → mount aus, die Instanz wird also erstellt, zerstört und erneut erstellt. Das Cleanup oben macht das sicher; es kostet in der Entwicklung einen zusätzlichen Aufruf Ihres Backends und in der Produktion keinen.
  • Halten Sie die Abhängigkeiten des Effects stabil. Ein Array-Literal, das aus einem Eltern-Render direkt in mount gereicht wird, ist bei jedem Render ein neuer Wert — ein Effect, der davon abhängt, reißt das Widget also bei jedem Render ab und baut es neu auf. Memoizen Sie es, oder halten Sie es konstant wie oben.

Events

Abonnieren Sie mit on, das eine Unsubscribe-Funktion zurückgibt. Handler erhalten die Event-Payload und den Mount, von dem sie kam; off(name, handler) erledigt dieselbe Aufgabe, wenn Sie den Handler lieber benennen.
Zehn Events. Jedes trägt ein network — außer ready und außer der einen Art von error, die sich gar nicht auf ein Netzwerk bezieht, siehe error hat zwei Quellen unten. Vier davon sind Endungensuccess, unlinked, error und cancelled —, und genau eine kommt pro Versuch an. closed ist eine Lifecycle-Meldung, die auf eine Endung folgt, statt selbst eine zu sein. click feuert, bevor irgendeine Verknüpfungsarbeit beginnt, meldet also auch einen Klick, den ein blockiertes Popup oder eine tote Session anschließend verweigert. Es ist das Event für Ihre eigenen Analysen; started ist das, das bedeutet, dass ein Versuch wirklich läuft.

Gründe

error hat zwei Quellen

Nur eine davon ist ein Verknüpfungsfehler, und sie tragen unterschiedliche Felder.
  • Ein Verknüpfungsfehler trägt network, code und den Mount, von dem er kam.
  • Ein Session-Fehler — wir konnten Ihre Session nicht erstellen oder erneuern — trägt nur message, weil zu dem Zeitpunkt nichts verknüpft wurde.
Destrukturieren Sie defensiv: code und network sind bei der zweiten Art undefined.

state erspart Ihnen das Polling

state ist der Datenkanal, kein Bericht über einen Versuch. Jeder Frame sendet beim Mounten eines pro Netzwerk, mit dem aktuellen Status dieses Netzwerks und dem since-Zeitstempel, seit dem er gilt, und ein weiteres bei jeder Statusänderung — einschließlich Änderungen, die auf unserer Seite entstehen, etwa ein Token, das in „Neuverknüpfung erforderlich“ übergeht. Sie können also Ihre gesamte UI aus dem Widget speisen, ohne irgendetwas zu pollen. Die Werte sind dasselbe Enum, das GET /profiles mit include=state zurückgibt: linked, unlinked, identityVerificationRequired, restricted, rateLimited, suspended.

Verknüpfung aufheben

Unsere Kacheln heben Verknüpfungen ebenso auf, wie sie sie herstellen. Ihr Nutzer klickt ein verbundenes Netzwerk an, bestätigt, und das Konto wird entfernt:
  1. click feuert mit action: "unlink".
  2. unlinked feuert, sobald die Entfernung gespeichert ist.
Ein Aufheben, das fehlschlägt, meldet error, und eines, aus dem Ihr Nutzer beim Bestätigungsschritt aussteigt, meldet cancelled. Ein separates Unlink-Failed-Event gibt es nicht.

Erscheinungsbild

Das Stylesheet eines Kunden kann nicht in einen Cross-Origin-Frame hineingreifen, deshalb reist das Styling als Daten, die wir darin anwenden. Übergeben Sie appearance an init als CSS Custom Properties; jede, die wir nicht erhalten, behält unseren Standardwert.
Setzen Sie Farben paarweise. Ein Hintergrund-Token ohne das zugehörige Vordergrund-Token ist der eine Weg, hiermit etwas Unlesbares zu erzeugen: Setzen Sie --ayr-connect-surface-bg allein auf einen dunklen Wert, bleibt unser Standard---ayr-connect-surface-fg weiterhin dunkles Marineblau. Nichts kann die andere Hälfte für Sie ableiten.
Ganz ohne appearance behält jedes Token seinen Standardwert, und ein Frame sieht so aus:
Drei Ayrshare-Connect-Kacheln mit dem Standard-Erscheinungsbild

Standard-Tokens: weiße Flächen, dunkler marineblauer Text, Indigo-Akzent, 8px Radius.

Übergeben Sie eine Handvoll Tokens, und derselbe Frame nimmt Ihre Palette an. Dieses Beispiel färbt die Flächen hellblau, vertieft Text und Akzent passend dazu und rundet die Ecken etwas stärker:
Drei Ayrshare-Connect-Kacheln, umgestylt mit hellblauen Flächen und einem tieferen Blau-Akzent

Dieselben drei Kacheln nach Anwendung der Tokens oben.

Es gibt eine Palette und kein Hell/Dunkel-Preset. Nichts reagiert auf prefers-color-scheme, und zwar absichtlich — das Theme Ihrer Seite muss nicht zum Betriebssystem Ihres Nutzers passen, und eine Media Query würde die von Ihnen gewählten Farben stillschweigend überstimmen. Ein dunkles Dashboard wird gethemt, indem Sie dunkle Werte übergeben. Diese Token-Liste ist ein unterstützter Vertrag, den wir über Versionen hinweg beibehalten.

Die Tokens

Ein Wert, der für sein Token kein gültiges CSS ist, wird ignoriert, mit einer Warnung in Ihrer Konsole, statt angewendet zu werden. Das ist wichtiger, als es klingt: Ein einheitenloses 8 für --ayr-connect-spacing ist ein völlig harmloser String, der jede darauf basierende Berechnung ungültig machen und das Layout kollabieren lassen würde, ohne irgendwo einen Fehler. Geben Sie Längen eine Einheit.

Ihr eigener Name auf dem Übergabebildschirm

Bevor wir Ihren Nutzer an ein Netzwerk übergeben, zeigen wir einen kurzen Bildschirm, der benennt, über wen die Verbindung läuft. Zwei Hooks machen ihn zu Ihrem eigenen, und beide sind versionsstabil. --ayr-connect-partner-name setzt das Label. Es ist das eine Token, dessen Wert Text ist, er muss also als CSS-String in Anführungszeichen stehen — ein Wert ohne Anführungszeichen ist ungültig und rendert gar nichts:
Das Logo ist kein Token. Wir liefern die Marke als positioniertes, dimensioniertes Element aus, und Sie füllen es über css mit einem background-image, wie oben — ein Token, das aus unserem Dokument heraus ein Bild laden könnte, akzeptieren wir nicht. Die Anfrage kommt also aus einer Regel, die Sie geschrieben haben, statt aus einem Wert, den Sie uns übergeben haben.
[data-ayr-connect-partner-mark] und [data-ayr-connect-partner-name] sind die Ausnahme vom Custom-CSS-Vorbehalt unten: Diese beiden Selektoren sind Teil des Vertrags, und wir behalten sie über Versionen hinweg bei.

Eigenes CSS

css nimmt einen String entgegen, der in jedem Frame angewendet wird — für die Fälle, die Tokens nicht abdecken.
Eigenes CSS wird über Versionen hinweg nicht unterstützt. Seine Selektoren zielen auf unser internes Markup, das sich zwischen Releases ändert — eine Regel, die heute funktioniert, kann nach jedem Update stillschweigend nicht mehr greifen. Der Token-Vertrag oben ist der Teil, den wir beibehalten. Pinnen Sie eine Version, wenn Sie auf eigenes CSS angewiesen sind.
Popups erben appearance und css der Instanz genauso wie Frames, sodass Ihr Nutzer nicht mitten in einem Ablauf unsere neutralen Standardwerte zu sehen bekommt.

Wissenswertes vor dem Release

Einem mit popup() geöffneten Popup kann nicht mitgeteilt werden, warum ein Token abgelehnt wurde — dafür müsste es einer Origin vertrauen, die es noch nicht validiert hat, was unser Sicherheitsmodell nicht erlaubt. Ein Popup mit totem Token schließt sich also und erscheint als cancelled mit reason: "popupClosed" statt als error.In der Praxis ist das selten: Ein vor einem stillen Refresh geöffnetes Popup funktioniert weiter, weil es sein Token beim Öffnen validiert hat. Sehen Sie unerklärte popupClosed-Ergebnisse, prüfen Sie, ob Ihr session-Endpunkt eine frische Session zurückgibt.
Vierzehn Mounts teilen sich ein Token und kosten einen Aufruf Ihres Backends, nicht vierzehn. Wenn Sie unterschiedlich beschränkte Slots möchten — ein anderes allowedSocial auf einigen davon —, starten Sie ein zweites init mit eigener Session, statt zu erwarten, dass ein Mount sie einschränkt.
Jede Session trägt die origin, auf der Ihre Seite läuft, und ein Frame vergleicht die Seite, die ihn einbettet, mit diesem Wert, bevor er irgendetwas rendert. Ein anderswo eingebetteter Frame bleibt leer und sendet keine Events. Es gibt keine Allowlist zu registrieren und nichts zu konfigurieren — senden Sie die richtige origin, wenn Sie die Session erstellen.
Frames melden ihre Höhe an das Skript, und das Skript passt sie an. Ihr Layout bricht einfach um. Es gibt kein Resize-Event zum Abonnieren und nichts, das Sie auf Ihrer Seite messen müssten.

Voraussetzungen

  • Der Max Pack. Eine Widget-Session ist eine Connect-Mode-Session, und eine ohne Max Pack zu erstellen gibt code: 504 zurück. Kontaktieren Sie den Support, wenn Sie den Connect Mode auf einem Account ohne Max Pack aktivieren müssen.
  • Ein origin auf jeder Session — die exakte Origin, auf der Ihre Seite läuft. 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.
  • Kein network auf der Session. Dieser Parameter macht eine Session stattdessen zu Direct Mode, und die URL einer Direct-Mode-Session ist nicht das, was das Skript erwartet.
Jeder der oben genannten Codes steht in der Referenz Link-Session-Fehler, mit der exakten Meldung, die die API zurückgibt, und was dagegen zu tun ist.