Welche Oberfläche Sie möchten

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

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

Gehostete Verknüpfungsseite: eine von uns gehostete Seite mit Ihrem Logo und Ihren Farben, für die Ihr Nutzer Ihre App verlässt.
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 — einintegrity-Attribut auf einer beweglichen URL funktioniert ab unserem nächsten Release nicht mehr,
weil sich die Datei dahinter legitim geändert hat.
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:
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: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.
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.
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
Einmount 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 stattdessenpopup auf. Es führt denselben Ablauf aus, auf derselben Session, und meldet sich über
dieselben Handler.
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.
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 dasnext/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.
- 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
mountgereicht 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 miton, 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.
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.
success, 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,codeund 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.
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:clickfeuert mitaction: "unlink".unlinkedfeuert, sobald die Entfernung gespeichert ist.
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 Sieappearance an init als CSS Custom
Properties; jede, die wir nicht erhalten, behält unseren Standardwert.
appearance behält jedes Token seinen Standardwert, und ein Frame sieht so aus:

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

Dieselben drei Kacheln nach Anwendung der Tokens oben.
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
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:
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.
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
Ein Popup mit abgelaufener Session meldet cancelled, nicht error
Ein Popup mit abgelaufener Session meldet cancelled, nicht error
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.Eine Session pro Instanz, nicht eine pro Mount
Eine Session pro Instanz, nicht eine pro Mount
allowedSocial auf einigen
davon —, starten Sie ein zweites init mit eigener Session, statt zu erwarten, dass ein Mount
sie einschränkt.Die Frames rendern nur auf der Origin, die Sie deklariert haben
Die Frames rendern nur auf der Origin, die Sie deklariert haben
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.Die Höhe wird für Sie verwaltet und ist kein Event
Die Höhe wird für Sie verwaltet und ist kein Event
Voraussetzungen
- Der Max Pack. Eine Widget-Session ist eine Connect-Mode-Session, und
eine ohne Max Pack zu erstellen gibt
code: 504zurück. Kontaktieren Sie den Support, wenn Sie den Connect Mode auf einem Account ohne Max Pack aktivieren müssen. - Ein
originauf jeder Session — die exakte Origin, auf der Ihre Seite läuft. Weglassen gibtcode: 505zurück; ein Wert, der keinehttps-Origin, kein Custom Scheme und nichthttp://localhostist, gibtcode: 506zurück. - Kein
networkauf 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.