Quelle surface choisir

Frames intégrées : nos tuiles affichées dans votre propre mise en page, un emplacement par réseau ou un emplacement pour plusieurs.

Votre propre bouton : vous affichez le bouton, et une brève popup de notre côté gère le réseau.

Page de liaison hébergée : une page que nous hébergeons, avec votre logo et vos couleurs, que votre utilisateur quitte votre application pour utiliser.
init vous donne les
deux : montez des frames là où vous voulez nos boutons, et appelez popup() depuis votre propre
bouton partout ailleurs. Elles partagent une même session et rapportent sur les mêmes handlers.Le mode direct est la même popup sans notre script —
pour une page avec une Content-Security-Policy stricte, une page rendue côté serveur ou une
application native. Là, c’est vous qui ouvrez et surveillez la popup.Ajouter le script
Épinglez une version et son hash, ou suivez un canal sans hash. Jamais les deux — un attributintegrity sur une URL mouvante cesse de fonctionner à notre prochaine release, car le fichier
qu’elle désigne a légitimement changé.
v1 est le canal à recommander. Il récupère les correctifs mais ne franchit jamais un
changement cassant. latest franchit les versions majeures par définition, donc il finira par
livrer à votre page une version dont vous n’avez pas examiné le comportement.
Le hash de chaque version est publié dans
manifest.json, qui indique également
ce que chaque canal sert actuellement :
Content-Security-Policy
Si votre page envoie une Content-Security-Policy, il lui faut deux entrées, toutes deux désignant l’hôte depuis lequel vous chargez le script :connect-src pour nous — nos
frames atteignent notre API depuis leur propre intérieur, pas depuis votre page — et d’aucune
entrée pour les popups, qui sont des fenêtres de premier niveau que votre politique ne gouverne
pas. Les deux entrées ont été mesurées : supprimer script-src bloque le script, et supprimer
frame-src bloque la frame.
Démarrer une instance
session est la seule option requise. Elle est appelée une fois par instance, pas une fois par
mount, et doit retourner la réponse de votre backend à
Créer une session de liaison avec mode: "connect" —
{ sessionId, token, expiresAt } — exactement telle qu’elle est arrivée.
network — elle autorise chaque réseau permis par votre
compte, et lesquels apparaissent se décide par mount, dans votre page. Elle porte en revanche un
origin, qui est la seule chose qui fait que les frames s’affichent : une frame vérifie la page
qui l’intègre par rapport à cette valeur et refuse de s’afficher partout ailleurs.
Nous rappelons session avant l’expiration du token, donc le widget continue de fonctionner sur
une page laissée ouverte toute la journée. Un appel qui rejette, ou qui ne retourne aucun token,
est retenté deux fois de plus — après 0,5 s, puis 1 s — avant que nous abandonnions et émettions
error. Un rafraîchissement coûte donc au plus trois appels à votre endpoint.
Monter un emplacement
Unmount par emplacement. Demandez un réseau, plusieurs, ou tout ce que la session permet — la
granularité vous appartient, donc un emplacement peut être une seule ligne d’un tableau existant
ou un panneau unique contenant tout.
mount prend un sélecteur CSS ou un élément, et retourne { unmount, element }. Il lève une
exception si la cible ne correspond à rien — ce qui est presque toujours un emplacement qui
n’existe pas encore, donc montez après que votre balisage est dans le document.
Chaque mount est une iframe. Elle nous rapporte sa propre hauteur et nous la redimensionnons pour
correspondre, donc votre mise en page se réorganise au fil des changements de notre contenu ;
au-delà de maxHeight, la frame défile en interne au lieu de déborder de votre page.
L’emplacement le plus étroit que nous prenons en charge est de 300px.
Les clés de réseau sont celles d’Ayrshare, et les graphies alias fonctionnent aussi : instagram
et instagramapi signifient tous deux instagramApi, et x signifie twitter. Une clé qui n’est
pas un réseau n’affiche aucune tuile.
Votre propre bouton
Un client qui préfère utiliser son propre bouton plutôt qu’une de nos frames appellepopup à la
place. Il exécute le même flux, sur la même session, et rapporte sur les mêmes handlers.
popup retourne { close(), network }, et retourne toujours un handle — y compris après une
popup bloquée, où close() ne fait rien — de sorte que votre code n’a jamais à vérifier la nullité
avant d’appeler close().
Tous les réseaux fonctionnent ici, y compris ceux qu’une frame termine dans son propre panneau :
Facebook affiche son écran d’explication de transfert dans la popup, Bluesky et X affichent leur
formulaire d’identifiants, et LinkedIn, Pinterest, YouTube et Google Business sortent vers le
réseau et reviennent.
Il lève une exception de manière synchrone pour les trois choses qui sont des erreurs de
programmation — pas de network, une instance détruite, ou une session qui n’a pas encore été
résolue. Une popup bloquée n’en fait pas partie : cela émet error avec
reason: "popupBlocked", car votre utilisateur n’a rien fait de mal.
Au plus une popup est ouverte à la fois. Un second appel ferme la première et rapporte cancelled
avec reason: "superseded" sur celle-ci. Une popup ouverte par une de nos frames est une chose
différente et n’est jamais touchée, donc votre bouton ne peut pas annuler un flux en cours dans un
emplacement monté.
error. Le script vérifie seulement qu’un réseau a bien été nommé.React
Le script est indépendant de tout framework, donc React ne nécessite rien de spécial de notre part — mais quatre choses concernant son cycle de vie méritent d’être bien faites dès la première fois. Chargez le script une seule fois, en dehors de votre arbre de composants. Dans Next.js, c’estnext/script dans votre layout racine ; dans Vite ou Create React App, c’est une balise dans
index.html. Le charger par composant le ré-exécute à chaque montage.
- En développement, vous verrez le callback de session se déclencher deux fois. Le Strict Mode de React exécute les effets montage → démontage → montage, donc l’instance est créée, détruite et recréée. Le nettoyage ci-dessus rend cela sûr ; cela coûte un appel supplémentaire à votre backend en dev et aucun en production.
- Gardez les dépendances de l’effet stables. Un littéral de tableau passé directement à
mountdepuis un rendu parent est une nouvelle valeur à chaque fois, donc un effet qui en dépend démonte le widget et le reconstruit à chaque rendu. Mémoïsez-le, ou gardez-le constant comme ci-dessus.
Événements
Abonnez-vous avecon, qui retourne une fonction de désabonnement. Les handlers reçoivent le
payload de l’événement et le mount dont il provient ; off(name, handler) fait le même travail
lorsque vous préférez nommer le handler.
network, à l’exception de ready et du seul type d’error qui
ne concerne pas du tout un réseau — voir error a deux sources
ci-dessous.
success, unlinked, error et cancelled — et
exactement un arrive par tentative. closed est un avis de cycle de vie qui suit une fin plutôt
que d’en être une.
click se déclenche avant tout travail de liaison, donc il rapporte un clic qu’une popup
bloquée ou une session morte refusera ensuite. C’est l’événement à utiliser pour vos propres
analytics ; started est celui qui signifie qu’une tentative est réellement en cours.
Raisons
error a deux sources
Une seule des deux est un échec de liaison, et elles portent des champs différents.
- Une erreur de liaison porte
network,codeet le mount dont elle provient. - Une erreur de session — nous n’avons pas pu créer ou rafraîchir votre session — ne porte que
message, car rien n’était en cours de liaison à ce moment-là.
code et network sont undefined sur le second type.
state vous épargne le polling
state est le canal de données plutôt qu’un rapport sur une tentative. Chaque frame en émet un par
réseau lorsqu’elle se monte, portant l’état actuel de ce réseau et le timestamp since depuis
lequel il le détient, et un autre à chaque changement d’état — y compris les changements qui
prennent naissance de notre côté, comme un token qui meurt et passe en relink-required. Vous
pouvez donc piloter toute votre UI depuis le widget sans rien poller.
Les valeurs sont le même enum que celui retourné par
GET /profiles avec include=state : linked, unlinked,
identityVerificationRequired, restricted, rateLimited, suspended.
Déliaison
Nos tuiles délient aussi bien qu’elles lient. Votre utilisateur clique sur un réseau connecté, confirme, et le compte est retiré :clickse déclenche avecaction: "unlink".unlinkedse déclenche une fois le retrait enregistré.
error, et une déliaison à laquelle votre utilisateur
renonce à l’étape de confirmation rapporte cancelled. Il n’existe pas d’événement séparé
d’échec de déliaison.
Apparence
La feuille de style d’un client ne peut pas atteindre l’intérieur d’une frame cross-origin, donc le style voyage sous forme de données que nous appliquons à l’intérieur. Passezappearance à init
sous forme de propriétés CSS personnalisées ; chacune que nous ne recevons pas conserve notre
valeur par défaut.
appearance, chaque token garde sa valeur par défaut et une frame ressemble à ceci :

Tokens par défaut : surfaces blanches, texte bleu marine foncé, accent indigo, rayon de 8px.

Les trois mêmes tuiles après application des tokens ci-dessus.
prefers-color-scheme, à dessein — le thème de votre page peut ne pas correspondre au système
d’exploitation de votre utilisateur, et une media query supplanterait silencieusement les couleurs
que vous avez choisies. Un tableau de bord sombre se thématise en fournissant des valeurs sombres.
Cette liste de tokens est un contrat pris en charge que nous maintenons d’une version à l’autre.
Les tokens
8 sans unité
pour --ayr-connect-spacing est une chaîne parfaitement innocente qui invaliderait tous les
calculs qui la lisent et effondrerait la mise en page, sans aucune erreur nulle part. Donnez une
unité aux longueurs.
Votre propre nom sur l’écran de transfert
Avant de confier votre utilisateur à un réseau, nous affichons un court écran indiquant via qui il se connecte. Deux hooks vous permettent de vous l’approprier, et tous deux sont stables d’une version à l’autre.--ayr-connect-partner-name définit le libellé. C’est le seul token dont la valeur est du
texte, donc elle doit être entre guillemets comme une chaîne CSS — une valeur sans guillemets
est invalide et n’affiche rien du tout :
background-image via css, comme ci-dessus — un token qui pourrait
récupérer une image depuis l’intérieur de notre document n’est pas quelque chose que nous
acceptons, donc la requête provient d’une règle que vous avez écrite plutôt que d’une valeur que
vous nous avez passée.
[data-ayr-connect-partner-mark] et [data-ayr-connect-partner-name] sont l’exception à la
mise en garde sur le CSS personnalisé ci-dessous : ces deux sélecteurs font partie du contrat et
nous les maintenons d’une version à l’autre.CSS personnalisé
css prend une chaîne appliquée dans chaque frame, pour les cas que les tokens ne couvrent pas.
appearance et css de l’instance exactement comme les frames, donc votre
utilisateur ne voit pas nos valeurs par défaut neutres apparaître au milieu d’un flux.
Bon à savoir avant de livrer
Une popup dont la session a expiré rapporte cancelled, pas error
Une popup dont la session a expiré rapporte cancelled, pas error
popup() ne peut pas se voir expliquer pourquoi un token
a été refusé — pour le dire, elle devrait faire confiance à une origine qu’elle n’a pas encore
validée, ce que notre modèle de sécurité n’autorise pas. Une popup portant un token mort se
ferme donc et remonte comme cancelled avec reason: "popupClosed" plutôt que comme error.En pratique, c’est rare : une popup ouverte avant un rafraîchissement silencieux continue de
fonctionner, car elle a validé son token à son ouverture. Si vous voyez des résultats
popupClosed inexpliqués, vérifiez que votre endpoint session retourne une session fraîche.Une session par instance, pas une par mount
Une session par instance, pas une par mount
allowedSocial différent sur
certains d’entre eux — exécutez un second init avec sa propre session plutôt que d’attendre
d’un mount qu’il la restreigne.Les frames ne s'affichent que sur l'origine que vous avez déclarée
Les frames ne s'affichent que sur l'origine que vous avez déclarée
origin sur laquelle votre page s’exécute, et une frame compare la page
qui l’intègre à cette valeur avant d’afficher quoi que ce soit. Une frame intégrée ailleurs
reste vide et n’envoie aucun événement. Il n’y a pas d’allowlist à enregistrer et rien à
configurer — envoyez la bonne origin lorsque vous créez la session.La hauteur est gérée pour vous, et n'est pas un événement
La hauteur est gérée pour vous, et n'est pas un événement
Prérequis
- Le Max Pack. Une session de widget est une session en mode connect,
et en créer une sans le Max Pack retourne
code: 504. Contactez le support si vous avez besoin du mode connect sur un compte qui ne l’a pas. - Un
originsur chaque session — l’origine exacte sur laquelle votre page s’exécute. L’omettre retournecode: 505; une valeur qui n’est pas une originehttps, un schéma personnalisé ouhttp://localhostretournecode: 506. - Pas de
networksur la session. Ce paramètre est ce qui fait d’une session du mode direct à la place, et l’URL d’une session en mode direct n’est pas ce que le script attend.