oEmbed de Facebook

Los puntos de conexión oEmbed de Facebook permiten obtener el código HTML de inserción y los metadatos básicos de páginas, publicaciones y videos con el fin de mostrarlos en otro sitio web o en otra app.

La función oEmbead Read reemplazó al producto oEmbed. Si implementaste el producto oEmbed antes del 8 de junio de 2021, tienes tiempo hasta el 7 de septiembre de 2021 para completar la revisión de apps para la función oEmbed Read. Si no cuentas con la función oEmbed Read aprobada para el 7 de septiembre de 2021, no se cargarán tus implementaciones de oEmbed.

Usos comunes

Representación de páginas, publicaciones y videos de Facebook en apps de mensajería.
Inserción de páginas, publicaciones y videos de Facebook en sitios web y blogs.
Representación de páginas, publicaciones y videos de Facebook en un sistema de administración de contenido.

Puntos de conexión

Punto de conexión	Descripción
`GET /oembed_page`	Permite obtener el código HTML de inserción y los metadatos básicos de una página de Facebook.
`GET /oembed_post`	Permite obtener el código HTML de inserción y los metadatos básicos de una publicación de Facebook.
`GET /oembed_video`	Permite obtener el código HTML de inserción y los metadatos básicos de un video de Facebook.

Requisitos

Una cuenta de desarrollador de Facebook
Una app de Facebook en modo activo
Un token de acceso
Revisión de apps para la función oEmbed Read

Limitaciones

Los puntos de conexión oEmbed de Facebook están destinados únicamente a usarse para insertar contenido de Facebook en sitios web y apps. No se los puede utilizar con otros fines. Está estrictamente prohibido el uso de los metadatos y el contenido de las páginas, las publicaciones o los videos (o sus derivados) del punto de conexión con cualquier fin que no sea el de ofrecer una visualización final de la página, publicación o video. La prohibición incluye el consumo, la manipulación, la extracción o el almacenamiento de metadatos y contenido, por ejemplo, la obtención de información sobre páginas, publicaciones y videos a partir de metadatos con fines de análisis.

Revisión de apps

Para usar oEmbed, tu app debe someterse a la revisión de apps en relación a la función oEmbed Read.

En el campo del formulario para proporcionar una URL en la que podamos probar oEmbed Read, usa el punto de conexión oEmbed de Instagram a fin de obtener el código HTML de inserción de publicaciones o videos públicos en nuestra página de Facebook o nuestra página de Instagram oficiales (o bien, obtén el código HTML de inserción de alguna de las páginas). Agrega el código HTML de inserción a la página de tu propiedad en la que mostrarás el contenido de oEmbed, e ingresa la URL de esa página en el campo del formulario.

Una vez que te hayan aprobado la función oEmbed Read, podrás insertar tus páginas, publicaciones o videos propios con las URL respectivas.

Tokens de acceso

El punto de conexión oEmbed de Facebook requiere un token de acceso a la app (recomendado) o un token de acceso de cliente.

Tokens de acceso a la app

Si tu app depende de un servidor de sistema interno, recomendamos que uses el token de acceso a la app cuando accedas al punto de conexión oEmbed. Los límites de frecuencia dependen del tipo de token incluido en la solicitud, y los límites de frecuencia de token de app permiten hasta 5 millones de solicitudes por día.

Puedes encontrar las instrucciones para generar tokens de acceso a la app en la sección de tokens de apps de nuestra documentación sobre tokens de acceso.

Ten en cuenta que los tokens de acceso a la app nunca pueden usarse del lado del cliente. Estos siempre deben estar protegidos y almacenados en tu servidor. En cambio, si tu app debe usar un token del lado del cliente, usa un token de acceso del cliente.

Tokens de acceso del cliente

Si tu app debe acceder al punto de conexión oEmbed desde un agente de usuario, como un dispositivo móvil o un navegador web, debe usar un token de acceso del cliente y estará sujeta a los límites de frecuencia del token de cliente.

Para obtener un token de acceso del cliente, inicia sesión en tu panel de apps y navega a Configuración > Avanzada > Seguridad > Token de cliente.

A diferencia de los tokens de acceso a la app, los tokens de acceso del cliente no se pueden usar en solicitudes de punto de conexión oEmbed solos, sino que deben estar combinados con tu identificador de la app. Para eso, agrega el token al final del identificador de la app, separado por una barra vertical (|):

{app-id}|{client-token}

Por ejemplo:

access_token=1234|5678

Límites de frecuencia

Los límites de frecuencia dependen del tipo de token de acceso que tu app incluye en cada solicitud.

Límites de frecuencia de token de la app

Las apps que dependen de tokens de acceso a la app pueden hacer hasta 5 millones de solicitudes cada 24 horas.

Límites de frecuencia de token de cliente

Los límites de frecuencia de token de cliente son bastante más bajos que los límites de frecuencia de token de la app. No revelamos el límite real porque este variará según la actividad de tu app. Sin embargo, puedes estar tranquilo de que tu app no alcanzará el límite a menos que tenga un comportamiento similar a un bot, como el procesamiento por lotes de miles de solicitudes o el envío de miles de solicitudes por agente o usuario de app.

Cómo obtener el código de inserción de HTML

Para obtener el código HTML de inserción de una página, una publicación o un video, envía una solicitud al punto de conexión oEmbed de la página, la publicación o el video correspondiente:

Destino	Punto de conexión y estructura de la consulta
Página	`GET /oembed_page?url={url}&access_token={access-token}`
Publicación	`GET /oembed_post?url={url}&access_token={access-token}`
Video	`GET /oembed_video?url={url}&access_token={access-token}`

Reemplaza {url} por la URL de la página, publicación o video que deseas consultar y {access-token} por el token de acceso del cliente o la app (o envíalo en un encabezado HTTP). Si usas un token de acceso del cliente, recuerda que debes combinarlo con el identificador de la app mediante un símbolo de barra vertical; de lo contrario, la solicitud no funcionará.

Si la solicitud se hace correctamente, la API responderá con un objeto JSON que contenga el código HTML de inserción y datos adicionales de la página, la publicación o el video. El código HTML de inserción se asignará a la propiedad html.

Consulta la referencia de cada punto de conexión para obtener una lista de los parámetros de cadena de consulta que puedes incluir para hacer una solicitud más compleja. También puedes incluir el parámetro de cadena de consulta fields en cualquier solicitud para especificar los campos que quieres que se devuelvan. Si omites esta información, todos los campos predeterminados se incluirán en la respuesta.

Ejemplo de solicitud de página

curl -i -X GET \
 "https://graph.facebook.com/v21.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC&access_token=96481..."

Ejemplo de respuesta

Para facilitar la lectura, se truncaron algunos valores y se agregaron puntos suspensivos (...).

{
  "provider_url": "https://www.facebook.com",
  "provider_name": "Facebook",
  "height": 500,
  "html": "<div id=\"fb-root\"></div><script async=\"1\" defer=...",
  "type": "rich",
  "version": "1.0",
  "width": 340
}

Formatos de URL

El parámetro de cadena de consulta url acepta los siguientes formatos de URL:

Páginas

https://www.facebook.com/{page-name}
https://www.facebook.com/{page-id}

Publicaciones

https://www.facebook.com/{page-name}/posts/{post-id}
https://www.facebook.com/{username}/posts/{post-id}
https://www.facebook.com/{username}/activity/{activity-id}
https://www.facebook.com/photo.php?fbid={photo-id}
https://www.facebook.com/photos/{photo-id}
https://www.facebook.com/permalink.php?story_fbid={post-id}&id={page-or-user-id}
https://www.facebook.com/media/set?set={set-id}
https://www.facebook.com/questions/{question-id}
https://www.facebook.com/notes/{username}/{note-url}/{note-id}

Videos

https://www.facebook.com/{page-name}/videos/{video-id}/
https://www.facebook.com/{username}/videos/{video-id}/
https://www.facebook.com/video.php?id={video-id}
https://www.facebook.com/video.php?v={video-id}

SDK para JavaScript

De forma predeterminada, el código HTML de inserción contiene una referencia a la biblioteca de JavaScript sdk.js. Incluye el parámetro de cadena de consulta omitscript=true para obtener el código HTML de inserción sin la referencia con el objetivo de cargarlo por separado.

Cómo enviar tokens de acceso en un encabezado

Si no quieres incluir el token de acceso en la cadena de consulta de la solicitud, puedes enviarlo a través de un encabezado HTTP Authorization.

Authorization: Bearer {access-token}

Por ejemplo:

curl -i -X GET \
  "https://graph.facebook.com/v21.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC" \
  --header "Authorization: Bearer 96481..."