Construisez votre propre popup de liaison

Le mode direct (Direct Mode) connecte un seul réseau social à la fois, depuis un bouton de votre propre tableau de bord. Vous créez une session de liaison pour ce réseau, ouvrez l’URL qu’elle retourne dans une popup, et votre page est informée de ce qui s’est passé. Votre utilisateur ne voit jamais de page listant tous les réseaux, et ne quitte jamais votre application plus longtemps que ne le prend la connexion du réseau lui-même.

Quelle surface choisir

Trois formes, et les deux premières sont la même intégration. Cette page est celle que vous construisez vous-même.

Surface	Votre utilisateur voit	Marque blanche	Choisissez-la quand
Widget — frames intégrées (mount)	nos boutons directement dans votre propre mise en page ; aucune popup avant celle du réseau lui-même	La plus forte. Votre page, vos polices et vos couleurs, et votre utilisateur ne la quitte jamais	vous avez un tableau de bord avec une ligne par réseau et voulez que la liaison se fasse sur place. Max Pack.
Widget — votre propre bouton (popup)	votre bouton, puis une seule popup pour le réseau	Forte. La popup est la nôtre, mais elle est brève et hérite de votre apparence	vous voulez votre propre bouton et votre propre style, et aucune frame dans votre mise en page. Max Pack.
Page de liaison hébergée (mode d’emploi)	une page que nous hébergeons, portant votre logo, vos couleurs et votre CSS personnalisé	La plus faible. C’est notre page, et votre utilisateur quitte la vôtre pour l’utiliser	vous voulez un lien unique à distribuer, ou vous intégrez par e-mail. Rien à construire, pas de Max Pack.

Le mode direct est la popup de la troisième ligne sans notre script. Si votre page peut charger le script, le widget fait tout ce que décrit cette page pour vous — il ouvre et surveille la popup lui-même, et il peut aussi intégrer des frames. Le mode direct est ce qu’il vous faut lorsque votre page ne peut pas charger un script tiers, ou que la surface est une application native plutôt qu’un navigateur.

Ce que vous construisez

Quatre étapes. La première est sur votre serveur, les autres dans votre page.

Créez une session pour un réseau

Depuis votre backend, appelez Créer une session de liaison avec mode: "connect", le network, et l’origin sur laquelle votre page s’exécute.

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();

Vous recevez en retour une url pointant vers une page de connexion mono-réseau, et aucun token — le token est à l’intérieur de l’URL. Traitez l’URL entière comme un mot de passe : elle connecte votre utilisateur à son User Profile.

Créez la session sur votre serveur, jamais dans le navigateur. L’appel nécessite votre clé API.

Ouvrez-la dans le gestionnaire de clic, de manière synchrone

La popup doit être ouverte par window.open dans le gestionnaire de clic lui-même. Un navigateur n’autorise une popup que tant qu’il est encore en train de traiter le clic de votre utilisateur, et cette autorisation ne survit pas à un await — donc récupérer d’abord l’URL et l’ouvrir dans le callback est systématiquement bloqué par le bloqueur de popups.Récupérez l’URL au moment où vous affichez le bouton, ou lorsque votre utilisateur le survole. Au moment du clic, vous devriez déjà l’avoir.

Your page

// `url` a été récupérée plus tôt. Rien d'asynchrone entre le clic et 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);
});

Écoutez le résultat

Parce que vous avez passé origin, la popup poste un événement à votre page pour chaque chose qui s’y produit : connect:success, connect:error, connect:cancelled, et des événements de progression entre les deux. Exactement l’un de ces trois arrive par connexion.Événements de fin de liaison contient le tableau complet des événements et un listener à copier-coller — listenForOutcome ci-dessus est ce snippet. Deux parties de celui-ci sont faciles à omettre et toutes deux causent de vrais bugs :

Vérifiez event.origin par rapport à l’origine de l’URL que vous avez ouverte. N’importe quelle page peut poster un message à votre fenêtre, et l’origine est la seule partie d’un message qui ne peut pas être falsifiée.
Pollez popup.closed, avec une courte fenêtre de grâce avant de conclure quoi que ce soit. Une popup que votre utilisateur a fermée à la main n’envoie rien du tout, et sans la fenêtre de grâce une connexion réussie peut être rapportée comme annulée.

Gérez chaque fin

Fin	Ce qu’elle signifie	Que faire
`connect:success`	le compte est connecté et enregistré	rafraîchissez cette ligne. Un `GET /user` juste après l’affiche déjà.
`connect:error`	la connexion a échoué	affichez `message`. `code` est présent lorsque l’échec a un code catalogué et absent lorsqu’il n’en a pas.
`connect:cancelled`	votre utilisateur a renoncé, ou a fermé la fenêtre	laissez la ligne telle quelle. `reason` est `popupClosed`, `scopesDenied` ou `userCancelled`.
rien n’arrive	le lien était expiré, révoqué ou inconnu, donc la page n’a jamais appris où envoyer les événements	pollez Obtenir une session de liaison, qui rapporte ces états de manière fiable.

Ajoutez &autoClose=false à l’URL pendant que vous construisez. La popup reste alors ouverte après chaque résultat au lieu de se fermer d’elle-même, pour que vous puissiez lire ce qu’elle affiche.

Notes par réseau

La plupart des réseaux, c’est une popup et rien d’autre : votre utilisateur clique, autorise auprès du réseau, et la popup se ferme. Voici les exceptions à connaître avant de construire.

X nécessite vos propres clés API

X en mode direct utilise vos identifiants X Developer App, fournis à la création de la session via les en-têtes X-Twitter-OAuth1-Api-Key et X-Twitter-OAuth1-Api-Secret sur Créer une session de liaison.Une session créée pour twitter ou x sans ces en-têtes est refusée à l’ouverture de la popup : votre utilisateur est informé que la connexion n’est pas disponible et ne voit aucun formulaire, et votre page reçoit connect:error avec un message et aucun code. C’est délibéré. L’identifiant manquant est le vôtre, pas celui de votre utilisateur, et les utilisateurs finaux ne doivent jamais avoir à saisir vos clés API.Comparez avec Bluesky, où le mot de passe d’application est l’identifiant propre de l’utilisateur final — celui-là, la page de connexion le collecte bien, dans un formulaire à l’intérieur de la popup.

Facebook affiche un bouton avant la connexion de Meta

network: "facebook" affiche un unique bouton dans la popup, et la connexion propre de Meta s’ouvre à partir de ce clic — Meta exige que sa connexion soit lancée par un clic à l’intérieur de la page qui héberge son SDK. Votre utilisateur clique deux fois plutôt qu’une ; rien d’autre ne diffère.Instagram se comporte de la même manière lorsqu’il est lié via une page Facebook — c’est-à-dire lorsque la session porte instagramLinkMethod: "facebook", ou lorsque le paramètre Instagram Login de votre compte sélectionne ce flux. Avec Instagram Login direct, il n’y a pas de bouton supplémentaire.

Bluesky et Telegram affichent du contenu de page, pas une redirection

Aucun des deux n’envoie votre utilisateur vers la connexion d’un réseau. La popup affiche du contenu à la place : un formulaire de handle et de mot de passe d’application pour Bluesky, et un code à utiliser pour Telegram. Les événements de résultat sont les mêmes dans les deux cas.X n’appartient pas à ce groupe. Avec vos clés sur la session, il se termine sans rien demander à votre utilisateur, et sans elles il est refusé — voir ci-dessus.

Telegram se termine hors bande

Telegram affiche un code plutôt que de rediriger où que ce soit, et la connexion se termine lorsque votre utilisateur utilise ce code — après la disparition de la popup. Il n’y a aucun événement navigateur à attendre, donc pollez Obtenir une session de liaison et surveillez completedNetworks.

Les groupes Facebook ne peuvent pas être connectés de cette manière

Facebook Groups n’est pas une cible de liaison, donc network: "fbg" retourne code: 508 lorsque vous créez la session.WhatsApp est disponible en mode direct. Il ouvre l’Embedded Signup de Meta dans la popup, et les événements de résultat sont les mêmes que pour tout autre réseau.

Applications natives

Une application native ouvre la même url, dans le navigateur système, et découvre le résultat en pollant Obtenir une session de liaison. Définissez origin sur votre schéma personnalisé (myapp://connected) pour que la page ait un moyen de revenir dans votre application ; un schéma personnalisé ne peut pas recevoir d’événements, car il n’y a pas de fenêtre de navigateur à laquelle les poster.

iOS — ASWebAuthenticationSession, ou SFSafariViewController.
Android — Chrome Custom Tabs.

N’ouvrez jamais une URL de liaison dans une webview intégrée (WKWebView, UIWebView, WebView Android). Les réseaux sociaux refusent de s’y authentifier : Google rejette la connexion avec disallowed_useragent, et Meta la bloque purement et simplement. Votre utilisateur voit la page d’erreur du réseau lui-même, pas la nôtre, et rien de ce que vous pouvez changer de votre côté n’y remédie. Les composants de navigateur système ci-dessus existent exactement pour cette raison et gardent l’utilisateur dans votre application.

Ce que le mode direct nécessite

Le Max Pack. Créer une session en mode connect sans lui retourne code: 504, quoi que dise le reste de la requête.
Un origin sur chaque session. Il n’y a pas d’allowlist ni d’étape d’enregistrement — vous l’envoyez à chaque appel. L’omettre retourne code: 505 ; une valeur qui n’est pas une origine https, un schéma personnalisé ou http://localhost retourne code: 506.
Un network que votre compte a activé. Un nom non reconnu retourne code: 508 ; un nom reconnu que votre compte n’a pas activé retourne code: 509, ce que vous pouvez corriger sur votre page Réseaux sociaux.
Pas d’allowedSocial. Il ne peut pas être combiné avec network (code: 507) — une session mono-réseau est déjà sa propre allowlist.

Chacun de ces codes figure dans la référence Erreurs de session de liaison, avec le message retourné par l’API.

Étapes suivantes

Événements de fin de liaison

Tous les événements que la popup envoie, et le listener pour les recevoir.

Voir aussi

Créer une session de liaison

Les paramètres mode, origin et network, et les formes de réponse.

Obtenir une session de liaison

Pollez la fin de liaison lorsque vous ne pouvez pas utiliser de popup.

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Quelle surface choisir

Ce que vous construisez

Notes par réseau

Applications natives

Ce que le mode direct nécessite

Étapes suivantes

Événements de fin de liaison

Voir aussi

Créer une session de liaison

Obtenir une session de liaison

​Quelle surface choisir

​Ce que vous construisez

​Notes par réseau

​Applications natives

​Ce que le mode direct nécessite

​Étapes suivantes

Événements de fin de liaison

​Voir aussi

Créer une session de liaison

Obtenir une session de liaison

Quelle surface choisir

Ce que vous construisez

Notes par réseau

Applications natives

Ce que le mode direct nécessite

Étapes suivantes

Voir aussi