Passer au contenu principal
Vos utilisateurs connectent eux-mêmes leurs propres comptes sociaux — ils s’authentifient directement auprès de chaque réseau, et vous ne voyez ni ne stockez jamais leurs identifiants. Tout sur cette page consiste à les amener jusqu’à ce moment et à savoir comment cela s’est passé. Une chose est commune à toutes les voies : une session de liaison, créée avec Créer une session de liaison à partir de votre clé API et d’une Profile-Key. Rien n’est signé de votre côté et aucune clé privée n’intervient dans le flux. La seule exception concerne les intégrations plus anciennes qui signent leurs propres tokens. Consultez Tokens auto-signés (historique).

Trois façons de connecter

Trois formes, et les deux premières sont la même intégration. Choisissez par flux — elles ne sont pas exclusives, et beaucoup d’intégrations utilisent la page hébergée pour l’onboarding et le widget dans l’application ensuite.
Les deux lignes du widget sont une seule intégration, pas deux. Un seul 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.Vous hésitez ? Commencez par la page de liaison hébergée. Elle ne nécessite ni Max Pack ni paramètres supplémentaires, et c’est la voie la plus rapide vers quelque chose qui fonctionne — passer au widget plus tard ne change pas la manière dont les sessions sont créées.

Créer un lien

Appelez Créer une session de liaison avec la Profile-Key de l’utilisateur dans l’en-tête. Pour la page hébergée, c’est là toute la requête :
cURL
Vous recevez en retour une url portant un token opaque de courte durée :
Linking URL
Vous pouvez également vérifier si un lien a été ouvert et le révoquer avant son expiration.
Cette vidéo d’une minute montre comment créer un lien. Elle a été enregistrée avant les sessions de liaison, donc elle montre encore l’envoi d’une Private Key — cette étape n’est plus nécessaire, et tout le reste de ce qu’elle montre est inchangé.

Envoyer l’URL de liaison

Une URL de liaison connecte votre utilisateur à son profil : traitez-la comme un mot de passe. Transmettez-la par un canal de confiance, ne la journalisez pas et ne la communiquez pas à un tiers. Elle reste utilisable pendant toute sa fenêtre, donc un rechargement ou une nouvelle tentative OAuth fonctionne — mais n’envoyez chaque lien qu’à un seul utilisateur et créez un lien distinct par personne.

Ouverture de l’URL de liaison

Ouvrez-la dans un nouvel onglet, une nouvelle fenêtre de navigateur ou un View Controller. Vous pouvez contrôler la fermeture ou la redirection de cette fenêtre.
Les réseaux sociaux ne permettent pas d’ouvrir la page de liaison hébergée dans une iFrame, ni de masquer l’origine du partenaire approuvé profile.ayrshare.com. Si vous voulez que la liaison se fasse à l’intérieur de votre propre page, c’est précisément le rôle du widget intégré : ses frames sont servies depuis une origine Ayrshare et constituent la manière prise en charge de le faire.

Savoir quand c’est terminé

Deux signaux, et vous pouvez utiliser l’un ou l’autre :
  • Événements de fin de liaison — définissez un origin lorsque vous créez le lien et la fenêtre de liaison poste connect:success, connect:error et connect:cancelled à votre page au fil des événements. Aucun polling.
  • Obtenir une session de liaison — rapporte completedAt, lastCompletedAt et completedNetworks. C’est le signal pour les applications natives, et le seul pour Telegram, qui se termine hors bande.

Expiration du lien

Un lien est valide pendant 5 minutes par défaut. Passé ce délai, créez-en un nouveau. Avec le Max Pack, définissez expiresIn en minutes pour élargir cette fenêtre — jusqu’à 2880 minutes (48 heures), qui est le maximum accepté par l’API :
Expires In
Une fenêtre plus longue est ce qui rend l’envoi du lien par e-mail praticable — un utilisateur qui reconnecte un compte perdu peut aller directement de votre e-mail au réseau, sans passer d’abord par votre application.
Vérifiez avec votre équipe de sécurité combien de temps un lien doit rester actif. Une fenêtre plus longue, c’est une période plus longue pendant laquelle un lien intercepté fonctionne encore. Si un lien s’échappe, vous pouvez le révoquer plutôt que d’attendre son expiration.

Sécurité

Le token de session circule dans la chaîne de requête de l’URL de liaison. Tout ce qui enregistre des URL peut l’enregistrer : l’historique du navigateur de l’utilisateur, les journaux de proxy et de serveur, les outils d’analyse et les services de redirection. Pour limiter le risque :
  • Ne journalisez pas l’URL complète dans vos propres systèmes. Journalisez plutôt le profil et l’heure.
  • Envoyez l’URL directement à l’utilisateur. Ne la faites pas passer par des raccourcisseurs de liens, des traceurs de redirection ou le suivi des clics dans les e-mails. L’e-mail Connect Accounts envoie le lien sans suivi des clics.
  • Gardez une fenêtre courte. Utilisez le expiresIn le plus court qui vous convienne (Max Pack).
  • Révoquez un lien dont vous soupçonnez la fuite, avec Révoquer une session de liaison.

Profile Key

La Profile-Key indique à quel User Profile le lien correspond. Vous la trouverez dans le tableau de bord développeur Ayrshare en basculant sur ce profil.
Vous n’avez pas besoin de la Private Key pour créer des liens. Les liens créés par l’API ne sont pas signés : il n’y a donc rien à lire depuis un fichier ni à coller dans votre code. Le paramètre historique privateKey est toujours accepté et ignoré, donc les intégrations existantes continuent de fonctionner.Si votre intégration signe ses propres tokens, conservez votre fichier private.key. Consultez Tokens auto-signés (historique).

Basculement entre les profils

Si un profil est déjà connecté, ouvrir le lien d’un autre profil ne change pas de profil — c’est délibéré, et cela rend l’expérience plus rapide pour un utilisateur déjà présent. Pour forcer un basculement, consultez Déconnexion automatique d’une session de profil. Les comptes Instagram peuvent être liés de deux manières : directement avec Instagram Login, ou via une page Facebook connectée. Le flux qui démarre lorsqu’un utilisateur clique sur le bouton Instagram est normalement contrôlé par le paramètre à l’échelle du compte Instagram Login. Le paramètre de corps instagramLinkMethod remplace ce paramètre pour un seul lien :
Instagram Link Method
Le remplacement s’applique pendant toute la durée de vie de ce lien, y compris à travers la redirection d’autorisation Instagram/Facebook. Quelques points à savoir :
  • Il ne modifie pas votre paramètre à l’échelle du compte ni n’affecte les autres liens.
  • Omettez-le et le paramètre à l’échelle du compte s’applique, exactement comme avant.
  • Une valeur invalide retourne 400 listant les valeurs valides (instagram, facebook).
  • Passez en revue les différences de fonctionnalités avant de choisir — certaines fonctionnalités Instagram, telles que la recherche de hashtags et les collaborations, ne sont disponibles qu’avec l’authentification via page Facebook.

E-mail Connect Accounts

Ayrshare peut envoyer le lien par e-mail à votre utilisateur pour vous, afin qu’il puisse accéder à sa page de liaison sans passer par votre application. Associez cela à un expiresIn plus long — les cinq minutes par défaut survivent rarement à une boîte de réception.

JSON Connect Accounts

Chaque champ à l’intérieur de email est requis. Un champ manquant fait échouer l’envoi.
Example Contact Email Request
expiresIn est un paramètre de premier niveau, pas une partie de l’objet email. Imbriqué dans email, il est ignoré, et votre utilisateur reçoit un lien qui expire au bout de cinq minutes.
La réponse indique le résultat dans emailSent :
Example Contact Email Response
Si l’e-mail ne peut pas être envoyé, la requête réussit quand même et vous recevez le lien. La réponse contient emailSent: false ainsi qu’un objet emailError, afin que vous puissiez transmettre le lien à votre utilisateur autrement :
Example Failed Email Response
emailError apparaît dès que vous avez demandé un e-mail et qu’il n’a pas été envoyé : soit l’envoi a échoué, soit il manquait un champ obligatoire dans l’objet email, auquel cas details indique les champs manquants. emailSent: false sans emailError signifie qu’aucun e-mail n’a été demandé. L’absence de to est un cas à part : toute la requête est rejetée avec code: 188.

Exemple d’e-mail Connect Accounts

Voici un exemple de l’e-mail qui ouvre la page de liaison sociale : Connect Accounts email L’e-mail provient de l’adresse : Social Connect Hub <connect@socialconnecthub.com>

Applications mobiles

Ouvrez l’URL de liaison dans le navigateur système, jamais dans une webview intégrée : Google rejette la connexion dans une webview avec disallowed_useragent, et Meta la bloque purement et simplement. Votre utilisateur verrait la page d’erreur du réseau lui-même, et rien de votre côté ne peut y remédier.
  • iOS — ASWebAuthenticationSession, ou SFSafariViewController.
  • Android — Chrome Custom Tabs.
Comme une application native n’a pas de fenêtre de navigateur à laquelle poster des événements, récupérez le résultat depuis Obtenir une session de liaison à la place. Définissez origin sur votre schéma personnalisé (myapp://connected) pour que la page ait un moyen de revenir dans votre application.

Exemples de code mobile

Remplacez linkingURL par l’url renvoyée par Créer une session de liaison.

Tests

Il est recommandé de d’abord créer un lien dans Postman. Votre Integration Package — sur la page API Key du Primary Profile dans le tableau de bord — inclut un exemple de configuration Postman. Importez-le, renseignez votre Profile Key dans le champ body profileKey, puis cliquez sur Send. La configuration d’exemple préremplit toujours privateKey et domain. privateKey est ignoré, et vous pouvez vider domain sauf si votre compte possède plusieurs domaines de liaison. Vous pouvez aussi générer le code depuis Postman.

Bubble.io

Bubble linking URL

Historique : generateJWT

Générer une URL de liaison (generateJWT) réalise la même opération et est déprécié — entièrement pris en charge, sans date de retrait, et inchangé pour les liens que vous avez déjà distribués. Sa propre page documente ses paramètres, y compris les trois qui sont désormais acceptés et ignorés.Les deux endpoints utilisent le même validateur, donc tout ce qui figure sur cette page s’applique à l’un comme à l’autre. La seule différence à connaître lors de votre migration : generateJWT tolère trois choses que Créer une session de liaison rejette — un réseau allowedSocial inconnu, un identifiant X isolé, et un redirect non textuel.

Tokens auto-signés (historique)

Certaines intégrations plus anciennes construisent elles-mêmes l’URL de liaison. Elles signent un token avec le fichier private.key de leur Integration Package et le transmettent via ?jwt=. Cela fonctionne toujours, et il n’y a aucune date de retrait. Ce n’est pas recommandé pour les nouvelles intégrations. Utilisez plutôt Créer une session de liaison. Si votre intégration signe ses propres tokens :
  • Continuez d’utiliser votre fichier private.key, et gardez-le secret.
  • Les liens auto-signés ne peuvent être ni vérifiés ni révoqués avec les endpoints de session de liaison.
  • Ne réinitialisez pas votre Integration Package. Une réinitialisation retire votre domaine actuel et ses clés : les liens déjà distribués cessent de fonctionner et vous ne pouvez plus en signer de nouveaux.
  • Un lien auto-signé n’expire que si son token définit une heure exp. expiresIn et la durée par défaut des sessions de liaison ne s’appliquent pas, gardez donc cette durée courte.
  • Traitez les URL de liens auto-signés comme un mot de passe. Si l’une d’elles a pu fuiter, réinitialisez votre clé API sur la page API du dashboard, puis mettez à jour votre intégration avec la nouvelle clé. Cela protège votre compte, mais n’empêche pas forcément le lien divulgué de fonctionner. Contactez le support pour bloquer le lien.