Facebook oEmbed

Facebook oEmbed 엔드포인트를 사용하면 페이지, 게시물, 동영상의 퍼가기 HTML과 기본 메타데이터를 가져와 다른 웹사이트나 앱에 표시할 수 있습니다.

oEmbed 제품이 oEmbed 읽기 기능으로 교체되었습니다. 2021년 6월 8일에 oEmbed 제품을 구현했을 경우 2021년 9월 7일까지 oEmbed 읽기 기능에 대한 앱 검수를 완료해야 합니다. 2021년 9월 7일까지 oEmbed 읽기 기능에 대한 승인을 받지 않았을 경우 oEmbed 구현을 읽어들이지 못합니다.

일반적인 사례

메시지 앱에서 Facebook 페이지, 게시물, 동영상을 렌더링합니다.
웹사이트와 블로그에 Facebook 페이지, 게시물, 동영상을 포함(embed)합니다.
콘텐츠 관리 시스템에서 Facebook 페이지, 게시물, 동영상을 렌더링합니다.

엔드포인트

엔드포인트	설명
`GET /oembed_page`	Facebook 페이지의 퍼가기 HTML과 기본 메타데이터를 가져옵니다.
`GET /oembed_post`	Facebook 게시물의 퍼가기 HTML과 기본 메타데이터를 가져옵니다.
`GET /oembed_video`	Facebook 동영상의 퍼가기 HTML과 기본 메타데이터를 가져옵니다.

요구 사항

제한 사항

Facebook oEmbed 엔드포인트는 웹사이트와 앱에 Facebook 콘텐츠를 포함(embed)하는 데만 사용해야 합니다. 그 외에 다른 용도로 사용해서는 안 됩니다. 페이지, 게시물 또는 동영상의 프런트 엔드 뷰를 제공하는 것 외에 다른 목적으로 엔드포인트의 메타데이터와 페이지, 게시물 또는 동영상 콘텐츠(또는 그 파생물)를 사용하는 것은 엄격히 금지됩니다. 이러한 금지 사항은 분석 목적으로 메타데이터에서 페이지, 게시물 및 동영상에 대한 정보를 파생하는 것을 포함하여(이에 국한되지 않음) 메타데이터와 콘텐츠의 사용, 조작, 추출 또는 지속까지 적용됩니다.

앱 검수

oEmbed를 사용하려면 앱이 oEmbed 읽기 기능에 대한 앱 검수를 거쳐야 합니다.

oEmbed 읽기를 테스트할 수 있는 URL 제공 양식 필드의 경우 oEmbed 엔드포인트를 사용하여 공식 Facebook 페이지 또는 Instagram 페이지의 모든 공개 게시물에 대한 퍼가기 HTML(또는 두 페이지 중 하나에 대한 퍼가기 HTML)을 가져옵니다. 반환된 퍼가기 HTML을 oEmbed 콘텐츠를 표시할 페이지에 추가하고 해당 페이지의 URL을 양식 필드에 입력합니다.

oEmbed 읽기 기능에 대한 승인을 받으면 각 URL을 사용하여 페이지, 게시물 또는 동영상을 포함할 수 있습니다.

액세스 토큰

Facebook oEmbed 엔드포인트는 앱 액세스 토큰(권장) 또는 클라이언트 액세스 토큰이 필요합니다.

앱 액세스 토큰

앱이 백엔드 서버를 사용할 경우 oEmbed 엔드포인트에 액세스할 때 앱 액세스 토큰을 사용하는 것이 좋습니다. 사용 제한은 요청에 포함된 토큰 유형에 따라 달라지고 앱 토큰 사용 제한은 하루에 최대 500만 건의 요청을 허용합니다.

앱 액세스 토큰 생성에 대한 지침은 액세스 토큰 문서의 앱 토큰 섹션에서 확인할 수 있습니다.

앱 액세스 토큰은 절대 클라이언트 측에서 사용해서는 안 됩니다. 앱 액세스 토큰은 언제나 서버에 안전하게 보관해야 합니다. 앱이 클라이언트 측에서 토큰을 사용해야 할 경우 클라이언트 액세스 토큰을 대신 사용하세요.

클라이언트 액세스 토큰

앱이 사용자 에이전트(예: 모바일 기기, 웹 브라우저)에서 oEmbed 엔드포인트에 액세스해야 할 경우 클라이언트 액세스 토큰을 사용해야 하며, 여기에는 클라이언트 토큰 사용 제한이 적용됩니다.

클라이언트 액세스 토큰을 가져오려면 앱 대시보드에 로그인하고 설정 > 고급 > 보안 > 클라이언트 토큰으로 이동합니다.

액세스 토큰과 달리 클라이언트 액세스 토큰은 oEmbed 엔드포인트 요청에 단독으로 사용할 수 없으므로 앱 ID와 결합해서 사용해야 합니다. 그렇게 하려면 앱 ID 끝에 토큰을 추가하고 파이프 기호(|)로 구분합니다.

{app-id}|{client-token}

예를 들면 다음과 같습니다.

access_token=1234|5678

사용 제한

사용 제한은 앱이 각 요청에 포함하는 액세스 토큰 유형에 따라 달라집니다.

앱 토큰 사용 제한

앱 액세스 토큰을 사용하는 앱은 24시간 동안 최대 500만 건의 요청을 보낼 수 있습니다.

클라이언트 토큰 사용 제한

클라이언트 토큰 사용 제한은 앱 토큰 사용 제한보다 현저히 낮습니다. 앱 활동에 따라 달라지기 때문에 실제 제한이 얼마인지는 공개하지 않습니다. 그러나 수천 건의 요청을 한 번에 보내거나 각 에이전트 또는 앱 사용자별로 수천 건의 요청을 전송하는 등, 봇과 유사한 행동을 하지 않는다면 앱이 사용 제한에 도달하지 않으므로 안심하셔도 됩니다.

퍼가기 HTML 가져오기

페이지, 게시물 또는 동영상의 퍼가기 HTML을 가져오려면 해당 페이지, 게시물 또는 동영상 oEmbed 엔드포인트로 요청을 보내세요.

타겟	엔드포인트 및 쿼리 구조
페이지	`GET /oembed_page?url={url}&access_token={access-token}`
게시물	`GET /oembed_post?url={url}&access_token={access-token}`
동영상	`GET /oembed_video?url={url}&access_token={access-token}`

{url}은 쿼리하고자 하는 페이지, 게시물 또는 동영상의 URL로 바꾸고 {access-token}은 앱 또는 클라이언트 액세스 토큰으로 바꿉니다(또는 HTTP 헤더에서 Facebook에 전달). 클라이언트 액세스 토큰을 사용하고 있다면 파이프 기호를 사용해 앱 ID와 결합하지 않을 경우 요청이 실패한다는 점을 기억하세요.

요청이 성공하면 API가 페이지, 게시물 또는 동영상의 퍼가기 HTML과 페이지, 게시물 또는 동영상에 대한 추가 데이터를 포함한 JSON 개체로 응답합니다. 퍼가기 HTML은 html 속성에 할당됩니다.

요청을 보강하기 위해 포함할 수 있는 쿼리 문자열 매개변수 리스트는 각 엔드포인트 참고 자료를 참조하세요. 또한 모든 요청의 fields 쿼리 문자열 매개변수를 포함하여 반환하고자 하는 필드를 지정할 수 있습니다. 이를 생략할 경우 모든 기본 필드가 응답에 포함됩니다.

샘플 페이지 요청

curl -i -X GET \
 "https://graph.facebook.com/v21.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}

SDK JS

기본적으로 퍼가기 HTML에는 sdk.js JavaScript 라이브러리에 대한 참조가 포함되어 있습니다. 별도로 읽어들이기 위해 참조 없이 퍼가기 HTML을 가져오려면 omitscript=true 쿼리 문자열 매개변수를 포함하세요.

헤더에서 액세스 토큰 전달

요청의 쿼리 문자열에 액세스 토큰을 포함하고 싶지 않다면 대신 Authorization HTTP 헤더를 통해 Facebook으로 전달할 수 있습니다.

Authorization: Bearer {access-token}

예를 들면 다음과 같습니다.

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