Skip to main content
Tus usuarios conectan sus propias cuentas sociales por sí mismos — se autentican directamente en cada red, y tú nunca ves ni almacenas sus credenciales. Todo lo que hay en esta página trata de llevarlos hasta ese momento y de averiguar cómo fue. Hay algo común a todas las vías: una sesión de vinculación, creada con Crear una Link Session a partir de tu API Key y una Profile-Key. No se firma nada en tu lado y no hay ninguna clave privada en el flujo.

Tres formas de conectar

Tres formas, y las dos primeras son la misma integración. Elige por flujo — no son excluyentes, y muchas integraciones usan la página alojada para la incorporación y el widget dentro de la app después.
Las dos filas del widget son una sola integración, no dos. Un único init te da ambas: monta frames donde quieras nuestros botones y llama a popup() desde tu propio botón en el resto de sitios. Comparten una misma sesión y reportan en los mismos handlers.El modo directo (Direct Mode) es la misma ventana emergente sin nuestro script — para una página con una Content-Security-Policy estricta, una página renderizada en servidor o una app nativa. Ahí abres y supervisas la ventana emergente tú mismo.¿No lo tienes claro? Empieza con la página de vinculación alojada. No necesita Max Pack ni parámetros adicionales, y es la vía más rápida hacia algo que funcione — pasar después al widget no cambia cómo se crean las sesiones.

Crear un enlace

Llama a Crear una Link Session con la Profile-Key del usuario en la cabecera. Para la página alojada, esa es toda la solicitud:
cURL
Recibes de vuelta una url que lleva un token opaco y de corta duración:
Linking URL
También puedes comprobar si un enlace se ha abierto y revocarlo antes de que caduque.
Este vídeo de un minuto muestra cómo crear un enlace. Se grabó antes de las link sessions, así que todavía muestra el envío de una Private Key — ese paso ya no es necesario, y todo lo demás que muestra no ha cambiado.

Enviar la URL de vinculación

Una URL de vinculación inicia la sesión de tu usuario en su perfil, así que trátala como una contraseña. Envíala por un canal de confianza, no la registres en logs y no la pases a terceros. Sigue siendo válida durante toda su ventana, así que una recarga o un reintento de OAuth funcionan — pero envía cada enlace a un solo usuario y crea un enlace distinto por persona.

Abrir la URL de vinculación

Ábrela en una nueva pestaña del navegador, una nueva ventana o un view controller. Puedes controlar el cierre o la redirección de esa ventana.
Las redes sociales no permiten abrir la página de vinculación alojada dentro de un iFrame, ni ofuscar el origen de partner autorizado profile.ayrshare.com. Si quieres que la vinculación ocurra dentro de tu propia página, para eso existe el widget incrustado: sus frames se sirven desde un origen de Ayrshare y son la forma admitida de hacerlo.

Saber cuándo ha terminado

Dos señales, y puedes usar cualquiera de las dos:
  • Eventos de finalización de vinculación — establece un origin al crear el enlace y la ventana de vinculación envía connect:success, connect:error y connect:cancelled a tu página según ocurren. Sin polling.
  • Obtener una Link Session — informa de completedAt, lastCompletedAt y completedNetworks. Esta es la señal para apps nativas, y la única para Telegram, que completa fuera de banda.

Caducidad del enlace

Un enlace es válido durante 5 minutos por defecto. Pasado ese tiempo, crea uno nuevo. Con el Max Pack, establece expiresIn en minutos para ampliar esa ventana — hasta 2880 minutos (48 horas), que es el máximo que acepta la API:
Expires In
Una ventana más larga es lo que hace práctico enviar el enlace por correo: un usuario que reconecta una cuenta caída puede ir directamente desde tu correo hasta la red, sin visitar antes tu aplicación.
Revisa con tu equipo de seguridad durante cuánto tiempo debe seguir vivo un enlace. Una ventana más larga es un periodo más largo en el que un enlace interceptado sigue funcionando. Si uno se filtra, puedes revocarlo en lugar de esperar a que caduque.

Profile Key

La Profile-Key identifica a qué User Profile corresponde el enlace. La encontrarás en el panel de desarrollador de Ayrshare cambiando a ese perfil.
La Private Key ya no se utiliza. Los enlaces no se firman, así que no hay nada que leer de un archivo ni que pegar en tu código. El parámetro heredado privateKey se sigue aceptando y se ignora, por lo que las integraciones existentes siguen funcionando, y el archivo private.key de tu Integration Package puede quedar sin usar.

Cambiar de perfil

Si un perfil ya ha iniciado sesión, abrir el enlace de otro perfil no cambia de perfil — esto es deliberado, y mantiene la experiencia rápida para un usuario que ya está ahí. Para forzar un cambio, consulta Cierre de sesión automático de una sesión de perfil. Las cuentas de Instagram pueden vincularse de dos maneras: directamente con Instagram Login, o a través de una Facebook Page conectada. El flujo que se inicia cuando un usuario hace clic en el botón de Instagram suele estar controlado por el ajuste global de la cuenta Instagram Login. El parámetro instagramLinkMethod del cuerpo sobrescribe ese ajuste para un único enlace:
Instagram Link Method
La sobrescritura se aplica durante toda la vida de ese enlace, incluida la redirección de autorización de Instagram/Facebook. Algunas cosas que debes saber:
  • No cambia el ajuste global de tu cuenta ni afecta a ningún otro enlace.
  • Si lo omites, se aplica el ajuste global de la cuenta, exactamente como antes.
  • Un valor no válido devuelve 400 con la lista de valores válidos (instagram, facebook).
  • Revisa las diferencias de funcionalidad antes de elegir — algunas funcionalidades de Instagram, como la búsqueda por hashtags y las colaboraciones, solo están disponibles con la autenticación mediante Facebook Page.

Connect Accounts Email

Ayrshare puede enviar el enlace por correo a tu usuario por ti, para que llegue a su página de vinculación sin visitar tu aplicación. Combínalo con un expiresIn más largo: los cinco minutos por defecto rara vez sobreviven a una bandeja de entrada.

Connect Accounts JSON

Todos los campos dentro de email son obligatorios. Si falta alguno, el envío falla.
Example Contact Email Request
expiresIn es un parámetro de nivel superior, no parte del objeto email. Anidado dentro de email se ignora, y tu usuario recibe un enlace que caduca en cinco minutos.
La respuesta informa del resultado en emailSent:
Example Contact Email Response
Si el correo no se puede enviar, la solicitud sigue teniendo éxito y recibes el enlace igualmente. La respuesta incluye emailSent: false y un objeto emailError, para que puedas enviar el enlace a tu usuario de otra forma:
Example Failed Email Response
emailError aparece siempre que pediste un correo y no se envió: o bien el envío falló, o bien al objeto email le faltaba un campo obligatorio, y en ese caso details indica los campos que faltan. emailSent: false sin emailError significa que no se solicitó ningún correo. Si falta to, es distinto: se rechaza toda la solicitud con code: 188.

Ejemplo de correo de Connect Accounts

Este es un ejemplo del correo que abre la página de vinculación social: Connect Accounts email El correo se envía desde: Social Connect Hub <connect@socialconnecthub.com>

Apps móviles

Abre la URL de vinculación en el navegador del sistema, nunca en un webview incrustado: Google rechaza el inicio de sesión en uno con disallowed_useragent, y Meta lo bloquea directamente. Tu usuario vería la página de error de la propia red, y nada en tu lado lo arregla.
  • iOS — ASWebAuthenticationSession, o SFSafariViewController.
  • Android — Chrome Custom Tabs.
Como una app nativa no tiene ventana de navegador a la que enviar eventos, obtén el resultado con Obtener una Link Session en su lugar. Establece origin con tu esquema personalizado (myapp://connected) para que la página tenga una vía de vuelta a tu app.

Ejemplos de código móvil

Reemplaza linkingURL con la url devuelta por Crear una Link Session.

Pruebas

Se recomienda crear primero un enlace en Postman. Tu Integration Package — en la página de API Key del Primary Profile del dashboard — incluye una configuración de ejemplo para Postman. Impórtala, rellena tu Profile Key en el campo profileKey del body y pulsa Send. La configuración de ejemplo todavía rellena privateKey y domain. privateKey se ignora, y puedes borrar domain salvo que tu cuenta tenga más de un dominio de vinculación. También puedes generar el código desde Postman.

Bubble.io

Bubble linking URL

Legado: generateJWT

Generar una URL de vinculación (generateJWT) hace el mismo trabajo y está deprecado — totalmente soportado, sin fecha de retirada y sin cambios para los enlaces que ya hayas repartido. Su propia página documenta sus parámetros, incluidos los tres que ahora se aceptan y se ignoran.Ambos endpoints ejecutan el mismo validador, así que todo lo de esta página se aplica a cualquiera de los dos. La única diferencia que merece la pena conocer al migrar: generateJWT tolera tres cosas que Crear una Link Session rechaza — una red allowedSocial no reconocida, una sola mitad de las credenciales de X y un redirect que no sea una cadena.