oEmbed do Facebook

Os pontos de extremidade oEmbed do Facebook permitem que você obtenha um HTML incorporado e os metadados básicos de páginas, publicações e vídeos para exibi-los em outro site ou app.

O produto oEmbed foi substituído pelo recurso oEmbed Read. Caso tenha implementado o produto oEmbed antes de 8 de junho de 2021, você deve concluir a análise do aplicativo para o recurso oEmbed Read até 7 de setembro de 2021. Se você não tiver recebido a aprovação para o recurso oEmbed Read até 7 de setembro de 2021, as suas implementações oEmbed não serão carregadas.

Usos comuns

Renderização de Páginas, publicações e vídeos do Facebook em apps de mensagem.
Incorporação de Páginas, publicações e vídeos do Facebook em sites e blogs.
Renderização de Páginas, publicações e vídeos do Facebook em um sistema de gerenciamento de conteúdo.

Pontos de extremidade

Ponto de extremidade	Descrição
`GET /oembed_page`	Obtenha um HTML incorporado e os metadados básicos de uma Página do Facebook.
`GET /oembed_post`	Obtenha um HTML incorporado e os metadados básicos de uma publicação do Facebook.
`GET /oembed_video`	Obtenha um HTML incorporado e os metadados básicos de um vídeo do Facebook.

Requisitos

Uma conta de desenvolvedor do Facebook
Um app do Facebook no modo Publicado
Um token de acesso
Análise do app para o recurso oEmbed Read

Limitações

Os pontos de extremidade oEmbed do Facebook devem ser usados somente para incorporar conteúdo do Facebook em sites e apps. Eles não devem ser usados para nenhum outro propósito. O uso de metadados e conteúdo de Páginas, publicações ou vídeos (ou derivados) dos pontos de extremidade para qualquer propósito que não o fornecimento de visualização de front-end da Página, da publicação ou do vídeo em questão é estritamente proibido. Essa proibição engloba o consumo, a manipulação, a extração ou a persistência de metadados e de conteúdo, incluindo, entre outros, obter informações sobre páginas, publicações e vídeos a partir dos metadados para fins de análise.

Análise do app

Para usar o oEmbed, seu app precisa passar pela análise para o recurso oEmbed Read.

No campo do formulário em que você fornece uma URL para o teste do oEmbed Read, use os pontos de extremidade oEmbed para obter o HTML incorporado de qualquer publicação aberta na nossa Página oficial no Facebook ou no Instagram (ou obtenha o HTML incorporado de qualquer uma das páginas). Adicione o HTML incorporado obtido à página onde o conteúdo oEmbed deverá ser exibido e insira a URL dessa página no campo do formulário.

Depois de receber a aprovação para o recurso oEmbed Read, você poderá incorporar páginas, publicações ou vídeos usando as respectivas URLs.

Tokens de acesso

Os pontos de extremidade oEmbed do Facebook requerem um token de acesso do app (recomendado) ou um token de acesso do cliente.

Tokens de acesso do app

Caso seu app dependa de um servidor de back-end, recomendamos que você use o token de acesso do app ao acessar o ponto de extremidade oEmbed. Os limites de volume dependem do tipo de token incluído na solicitação, e os limites de volume do token do app permitem até 5 milhões de solicitações por dia.

Para ver instruções sobre como gerar esses tokens, consulte a seção sobre tokens do app da nossa documentação sobre tokens de acesso.

Lembre-se de que os tokens de acesso do app nunca devem ser usados no lado do cliente. Eles devem ser mantidos em segurança e armazenados no seu servidor. Se o app precisar usar um token no lado do cliente, use um token de acesso do cliente.

Tokens de acesso do cliente

Caso o app precise acessar o ponto de extremidade oEmbed a partir de um agente do usuário (como um dispositivo móvel ou um navegador da web), o app deverá usar um token de acesso do cliente e estará sujeito aos limites de volume correspondentes.

Para obter um token de acesso do cliente, entre no Painel de Apps e navegue até Configurações > Avançado > Segurança > Token de cliente.

Ao contrário dos tokens de acesso do app, os tokens de acesso do cliente não podem ser usados em solicitações do ponto de extremidade oEmbed sozinhos. Eles devem ser combinados com o ID do app. Para fazer isso, adicione seu token ao final do ID do app, separado por um símbolo de barra (|):

{app-id}|{client-token}

Por exemplo:

access_token=1234|5678

Limites de volume

Os limites de volume dependem do tipo de token de acesso que seu app inclui em cada solicitação.

Limites de volume do token do app

Os apps que dependem de tokens de acesso do app podem fazer até 5 milhões de solicitações em 24 horas.

Limites de volume do token de cliente

Os limites de volume do token de cliente são significativamente mais baixos em comparação aos do token do app. Não revelamos o limite real, pois ele mudará dependendo da atividade do app. Contudo, você pode supor com segurança que seu app não alcançará o limite a menos que ele exiba um comportamento similar a um bot, como fazer milhares de solicitações em lote ou enviar milhares de solicitações por agente ou usuário.

Obter HTML incorporado

Para obter o HTML incorporado de uma Página, publicação ou vídeo, envie uma solicitação para o ponto de extremidade oEmbed da Página, publicação ou vídeo:

Tipo	Ponto de extremidade e estrutura de consulta
Página	`GET /oembed_page?url={url}&access_token={access-token}`
Publicação	`GET /oembed_post?url={url}&access_token={access-token}`
Vídeo	`GET /oembed_video?url={url}&access_token={access-token}`

Substitua {url} pela URL da Página, da publicação ou do vídeo que você quer consultar e {access-token} pelo token de acesso do cliente ou app (ou passe-o para nós em um cabeçalho HTTP). Se estiver usando um token de acesso do cliente, lembre-se de que você deve combiná-lo com o ID do app usando um símbolo de barra, do contrário, a solicitação falhará.

Caso a solicitação seja bem-sucedida, a API responderá com um objeto JSON contendo o HTML incorporado e os dados adicionais da Página, da publicação ou do vídeo. O HTML incorporado será atribuído à propriedade html.

Consulte a referência de cada ponto de extremidade para ver uma lista dos parâmetros da string de consulta que você pode incluir para aumentar a solicitação. Além disso, é possível incluir o parâmetro da string de consulta fields em qualquer solicitação para especificar os campos que você deseja que sejam retornados. Caso ele seja omitido, todos os campos padrão serão incluídos na resposta.

Exemplo de solicitação de Página

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

Exemplo de resposta

Alguns valores foram reduzidos com reticências (...) para facilitar a leitura.

{
  "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

O parâmetro da string de consulta url aceita os seguintes formatos de URL:

Páginas

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

Publicações

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}

SDK para JavaScript

Por padrão, o HTML incorporado contém uma referência à biblioteca de JavaScript sdk.js. Para obter um HTML incorporado sem a referência a fim de carregá-lo separadamente, inclua o parâmetro da string de consulta omitscript=true.

Como transmitir tokens de acesso por cabeçalhos

Se você não quiser incluir seu token de acesso na string de consulta da solicitação, transmita-o para nós por meio de um cabeçalho HTTP Authorization.

Authorization: Bearer {access-token}

Por exemplo:

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