oEmbed для Facebook

Конечные точки oEmbed для Facebook позволяют встраивать HTML-код и базовые метаданные страниц, публикаций и видео для отображения на другом сайте или в другом приложении.

Стандартное использование

• Отображение Страниц Facebook, публикаций и видео в приложениях для обмена сообщениями.
• Встраивание Страниц Facebook, публикаций и видео на сайты и в блоги.
• Отображение Страниц Facebook, публикаций и видео в системах управления контентом.

Конечные точки

Требования

• Аккаунт разработчика Facebook.
• Приложение Facebook в рабочем режиме.
• Маркер доступа.
• Проверка приложения для функции oEmbed Read.

Ограничения

Конечные точки oEmbed для Facebook предназначены только для встраивания контента Facebook на другие сайты или в приложения. Использовать их в любых других целях запрещено. Строго запрещается использовать метаданные и контент страниц, публикаций или видео и их производные, полученные с помощью этих конечных точек, в любых целях, кроме отображения этих страниц, публикаций или видео в пользовательском интерфейсе. Этот запрет распространяется на потребление, изменение, извлечение и хранение метаданных и контента, в том числе на получение из метаданных информации о страницах, публикациях и видео в целях анализа.

Проверка приложения

Чтобы использовать oEmbed, ваше приложение должно пройти проверку для функции oEmbed Read.

Для поля формы URL для тестирования oEmbed Read укажите конечные точки oEmbed, чтобы получить HTML-код для встраивания любой общедоступной публикации или видео на нашей официальной Странице Facebook или странице Instagram (или получите HTML-код для встраивания на любой из этих страниц). Добавьте полученный HTML-код для встраивания на собственную страницу, где будет отображаться контент oEmbed, и введите URL этой страницы в поле формы.

Получив одобрение на использование функции oEmbed Read, вы сможете встраивать собственные страницы, публикации и видео с помощью соответствующих URL.

Маркеры доступа

Для конечных точек oEmbed для Facebook требуется маркер доступа приложения (рекомендуется) или маркер доступа клиента.

Маркеры доступа приложения

Если ваше приложение работает на сервере, для доступа к конечной точке oEmbed рекомендуется использовать маркер доступа приложения. Ограничения числа обращений зависят от типа маркера доступа, указанного в запросе. Ограничение для маркера доступа приложения составляет 5 миллионов запросов в день.

Инструкции по генерации маркера доступа приложения можно найти здесь.

Обратите внимание: маркеры доступа приложения не следует использовать на стороне клиента. Они должны храниться в безопасности на вашем сервере. Если вашему приложению необходим маркер доступа на стороне клиента, используйте маркер доступа клиента.

Маркеры доступа клиента

Если вашему приложению нужно обращаться к конечной точке oEmbed из пользовательского агента, например с мобильного устройства или из браузера, используйте маркер доступа клиента. В таком случае для него будут действовать соответствующие ограничения числа обращений.

Чтобы получить маркер доступа клиента, войдите в панель приложений и перейдите в раздел Настройки > Расширенные > Безопасность > Маркер клиента.

В отличие от маркеров доступа приложения, маркеры доступа клиента нельзя использовать в запросах к конечной точке oEmbed самостоятельно: к ним всегда нужно добавлять ID вашего приложения. Для этого добавьте маркер доступа в конце ID приложения, отделив его вертикальной чертой (|):

{app-id}|{client-token}

Пример:

access_token=1234|5678

Ограничения числа обращений

Ограничения числа обращений зависят от типа маркера доступа, который приложение указывает в каждом запросе.

Ограничения числа обращений для маркера приложения

Приложения, использующие маркер доступа приложения, могут выполнять до 5 миллионов запросов каждые 24 часа.

Ограничения числа обращений для маркера клиента

Ограничения числа обращений для маркера клиента значительно ниже ограничений для маркера приложения. Указать точное ограничение невозможно, так как оно изменяется в зависимости от активности приложения. В большинстве случаев ваше приложение не достигнет ограничения, если оно не ведет себя как бот (в частности, не отправляет тысячи запросов в одном пакете или тысячи запросов на каждый агент либо каждого пользователя).

Получение HTML-кода для встраивания

Чтобы получить HTML-код для встраивания страницы, публикации или видео, отправьте запрос к соответствующей конечной точке oEmbed:

Замените {url} на URL Страницы, публикации или видео, которые вы хотите запросить, а {access-token} — на маркер доступа приложения или клиента (или передайте его нам в заголовке HTTP). Если вы используете маркер доступа клиента, не забудьте добавить к нему ID приложения, отделив вертикальной чертой.

В случае успеха API вернет объект JSON, содержащий HTML-код для встраивания и дополнительные данные о странице, публикации или видео. HTML-код для встраивания содержится в свойстве html.

Список дополнительных параметров строки запроса см. в справке по соответствующей конечной точке. В запрос также можно добавить параметр fields, чтобы указать, какие поля вы хотите получить в ответе. Если его не задать, будут возвращены все поля по умолчанию.

• Справка по конечным точкам oEmbed для страниц
• Справка по конечным точкам oEmbed для публикаций
• Справка по конечным точкам oEmbed для видео

Пример запроса для страницы

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

Пример ответа

Некоторые значения усечены (...) для удобства чтения.

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

Форматы URL

Параметр строки запроса url принимает URL в перечисленных далее форматах.

Страницы

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

Публикации

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}

Видео

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}

Facebook SDK для JavaScript

По умолчанию HTML-код для встраивания ссылается на библиотеку JavaScript sdk.js. Чтобы получить HTML-код без ссылки на библиотеку и загрузить ее отдельно, добавьте в запрос параметр omitscript=true.

Передача маркеров доступа в заголовке

Если вы не хотите указывать маркер доступа в строке запроса, его можно передать в HTTP-заголовке Authorization.

Authorization: Bearer {access-token}

Пример:

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