oEmbed de Facebook

Los extremos oEmbed de Facebook permiten obtener el código HTML de inserción y los metadatos básicos de páginas, publicaciones y vídeos para mostrarlos en otro sitio web o aplicación.

El producto oEmbed se ha reemplazado por la función oEmbed Read. Si implementaste el producto oEmbed antes del 8 de junio de 2021, tienes hasta el 7 de septiembre de 2021 para completar la revisión de la aplicación de la función oEmbed Read. Si no recibes la aprobación para la función oEmbed Read antes del 7 de septiembre de 2021, no podrás cargar las implementaciones de oEmbed.

Usos habituales

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

Extremos

Extremo	Descripción
`GET /oembed_page`	Obtiene el código HTML de inserción y los metadatos básicos de una página de Facebook.
`GET /oembed_post`	Obtiene el código HTML de inserción y los metadatos básicos de una publicación de Facebook.
`GET /oembed_video`	Obtiene el código HTML de inserción y los metadatos básicos de un vídeo de Facebook.

Requisitos

Una cuenta de desarrollador de Facebook
Una aplicación de Facebook en modo publicado
Un identificador de acceso
Revisión de la aplicación de la función oEmbed Read

Limitaciones

Los extremos oEmbed de Facebook solo están diseñados para utilizarse para insertar contenido de Facebook en sitios web y aplicaciones. No están destinados a ningún otro fin. Queda estrictamente prohibido utilizar contenido de vídeos, publicaciones, páginas y metadatos (o sus derivados) de los extremos para finalidades que no sean proporcionar una vista de front-end de la página, la publicación o el vídeo. Esta prohibición abarca el consumo, la manipulación, la extracción o la conservación de los metadatos y el contenido, lo que incluye, sin limitación, la derivación de información sobre páginas, publicaciones y vídeos de los metadatos con fines de análisis.

Revisión de la aplicación

Para utilizar oEmbed, tu aplicación debe someterse a la revisión de la aplicación para la función oEmbed Read.

En el campo del formulario Proporciona una URL en la que podamos probar oEmbed Read, usa los extremos oEmbed para obtener el código HTML de inserción de cualquier publicación o vídeo público en nuestra página de Facebook o página de Instagram oficial (u obtén el código HTML de inserción de cualquiera de las páginas). Añade el código HTML de inserción devuelto a la página en la que mostrarás el contenido de oEmbed e introduce la URL de dicha página en el campo del formulario.

Una vez que hayas recibido aprobación para la función oEmbed Read, podrás insertar tus páginas, publicaciones o vídeos con sus URL correspondientes.

Identificadores de acceso

Los extremos oEmbed de Facebook requieren un identificador de acceso a la aplicación (recomendado) o un identificador de acceso del cliente.

Identificadores de acceso a la aplicación

Si tu aplicación depende de un servidor de back-end, te recomendamos utilizar un identificador de acceso a la aplicación al acceder al extremo oEmbed. Las limitaciones de frecuencia dependen del tipo de identificador incluido en la solicitud y las del identificador de la aplicación permiten un máximo de 5 millones de solicitudes al día.

Puedes encontrar instrucciones sobre cómo generar identificadores de acceso a la aplicación en la sección Identificadores de la aplicación de nuestra documentación Identificadores de acceso.

Ten en cuenta que los identificadores de acceso a la aplicación nunca deben usarse en el lado del cliente. Siempre deben mantenerse protegidos y almacenados en el servidor. Si la aplicación necesita usar un identificador en el lado del cliente, utiliza un identificador de acceso del cliente en su lugar.

Identificadores de acceso del cliente

Si tu aplicación debe acceder al extremo oEmbed desde un agente de usuario, como un dispositivo móvil o navegador web, deberá utilizar un identificador de acceso del cliente y estar sujeto a las limitaciones de frecuencia del identificador del cliente.

Para obtener un identificador de acceso del cliente, inicia sesión en el panel de aplicaciones y ve a Configuración > Opciones avanzadas > Seguridad > Identificador de cliente.

A diferencia de los identificadores de acceso a la aplicación, los identificadores de acceso del cliente no se pueden utilizar en solicitudes del extremo oEmbed solos, sino que deben combinarse con el identificador de la aplicación. Para ello, anexa el identificador al final del identificador de la aplicación, separado por una barra vertical (|):

{app-id}|{client-token}

Por ejemplo:

access_token=1234|5678

Límites de frecuencia

Las limitaciones de frecuencia dependen del tipo de identificador de acceso que la aplicación incluye en cada solicitud.

Limitaciones de frecuencia de los identificadores de la aplicación

Las aplicaciones que dependen de identificadores de acceso a la aplicación pueden realizar hasta 5 millones de solicitudes cada 24 horas.

Limitaciones de frecuencia de los identificadores del cliente

Las limitaciones de frecuencia del identificador del cliente son considerablemente menores que las del identificador de la aplicación. No revelamos la limitación real, ya que cambiará en función de la actividad de la aplicación. No obstante, puedes suponer con seguridad que tu aplicación no alcanzará la limitación, a menos que muestre un comportamiento similar al de un bot; por ejemplo, si procesa por lotes miles de solicitudes o envía miles de solicitudes por agente o usuario de la aplicación.

Obtener el código HTML de inserción

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

Destino	Extremo y estructura de las consultas
Página	`GET /oembed_page?url={url}&access_token={access-token}`
Publicación	`GET /oembed_post?url={url}&access_token={access-token}`
Vídeo	`GET /oembed_video?url={url}&access_token={access-token}`

Reemplaza {url} por la URL de la página, la publicación o el vídeo que quieras consultar y {access-token} por el identificador de acceso del cliente o a la aplicación (o bien pásanoslo en un encabezado HTTP). Si utilizas un identificador de acceso del cliente, recuerda que debes combinarlo con tu identificador de la aplicación mediante una barra vertical, ya que, de lo contrario, se producirá un error en la solicitud.

Si la operación se completa correctamente, la API responderá con un objeto JSON que incluirá el código HTML de inserción y datos adicionales de la página, la publicación o el vídeo. El código HTML de inserción se asignará a la propiedad html.

Consulta la referencia de cada extremo para obtener una lista de los parámetros de cadena de consulta que puedes incluir para incrementar la solicitud. También puedes incluir el parámetro de cadena de consulta fields en cualquier solicitud para especificar los campos que quieres que se te devuelvan. Si se omite, 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

Algunos valores se truncan con puntos suspensivos (...) por motivos de legibilidad.

{
  "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 la cadena de consulta url acepta los formatos de URL siguientes:

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}

Vídeos

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}

JS del SDK

De manera predeterminada, el código HTML de inserción contiene una referencia a la biblioteca JavaScript sdk.js. Para obtener el código HTML de inserción sin la referencia para que puedas cargarlo por separado, incluye el parámetro de cadena de consulta omitscript=true.

Pasar identificadores de acceso en un encabezado

Si no quieres incluir el identificador de acceso en la cadena de consulta de la solicitud, puedes pasárnoslo 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..."