Messenger 확장 기능 SDK 추가하기

Messenger 확장 기능 SDK는 Messenger 웹 보기에서 열리는 웹사이트나 웹 앱에 Messenger의 중요한 기능을 제공합니다. 이 SDK를 사용하면 웹 보기를 연 사용자에 대한 정보를 검색하고, Messenger 대화에 콘텐츠를 공유하고, Messenger UI와 긴밀하게 통합할 수 있습니다.

사용 가능한 기능

Messenger 확장 기능 SDK를 포함할 때 Messenger 웹 보기에서 사용 가능한 기능은 다음과 같습니다. Messenger와 기기의 버전에 따라 기능의 실제 사용 여부는 달라질 수 있습니다.

함수	설명
getContext()	웹 보기를 연 사용자의 PSID와 같은 대화 컨텍스트를 검색합니다.
requestCloseBrowser()	웹 보기를 닫고 Messenger 대화로 돌아갑니다.
askPermission()	사용자 프로필 정보를 검색하는 등의 작업에 대한 권한을 요청합니다.
getGrantedPermissions()	현재 부여된 권한을 확인합니다.
getSupportedFeatures	현재 기기에서 웹 보기에 지원되는 기능(예: 공유)을 확인합니다.

이러한 기능을 사용하는 방법에 대한 자세한 내용은 Messenger 확장 기능 SDK 참고 자료를 참조하세요.

SDK 설치하기

1. 도메인을 화이트리스트에 등록하기

봇에서 Messenger 확장 기능을 사용하려면 먼저 페이지를 제공하는 도메인을 화이트리스트에 등록해야 합니다. 보안을 위해 웹페이지의 모든 도메인을 화이트리스트에 등록된 도메인에 추가해야 합니다. 자세한 내용은 화이트리스트 등록에 관한 참조 문서를 참조하세요.

다음 API를 사용하여 프로그래밍 방식으로 도메인을 화이트리스트에 쉽게 추가할 수 있습니다.

 
curl -X POST -H "Content-Type: application/json" -d '{
  "whitelisted_domains":[
    "https://petersfancyapparel.com"
  ]
}' "https://graph.facebook.com/v21.0/me/messenger_profile?access_token=PAGE_ACCESS_TOKEN"

성공 시 Messenger 프로필 API가 다음과 같이 응답합니다.

{"result":"success"}

2. Messenger 확장 기능 JS SDK 포함하기

아래의 코드를 사용하여 Messenger 확장 기능 Javascript SDK를 웹 보기에서 읽어들이는 페이지에 추가합니다. 읽어들이고자 하는 각 페이지에서 body 태그를 연 다음에 직접 삽입해야 합니다.

(function(d, s, id){
  var js, fjs = d.getElementsByTagName(s)[0];
  if (d.getElementById(id)) {return;}
  js = d.createElement(s); js.id = id;
  js.src = "//connect.facebook.net/en_US/messenger.Extensions.js";
  fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'Messenger'));

3. SDK 로드 이벤트 대기

window.extAsyncInit() 은 Messenger 확장 기능 JS SDK가 읽어들이기를 완료하면 호출됩니다. 이를 트리거로 사용하여 SDK에서 사용 가능한 다른 기능을 호출할 수 있습니다.

window.extAsyncInit = function() {
  // the Messenger Extensions JS SDK is done loading 
};

Messenger 웹 클라이언트에서 SDK 사용하기

모바일 및 데스크톱 Messenger 클라이언트에서 모두 Messenger 확장 기능 SDK가 지원됩니다. 그러나 SDK가 적절히 작동하려면 다음을 고려해야 할 수도 있습니다.

또한 window.name 속성을 사용하여 클라이언트 측 코드의 iframe 위치를 확인할 수 있습니다.

iframe이 Messenger 웹에서 트리거되면 window.name 이 'messenger_ref'로 설정됩니다. 그렇지 않으면 Facebook 채팅 탭에서 읽어들였을 때 window.name 이 'facebook_ref'가 됩니다.

지원되지 않는 기능

Messenger 웹 클라이언트에서는 다음 설정이나 기능이 지원되지 않습니다. 단, Messenger 모바일 클라이언트에서는 여전히 제대로 작동합니다.

webview_height_ratio
webview_share_button
탐색 뒤로 버튼
대화 상자 제목
URL 리디렉션을 통해 웹 보기 닫기

문제 해결

페이지에서 Messenger 확장 기능 SDK를 호출할 수 없을 경우 다음을 고려하세요.

고정 메뉴 또는 버튼에서 웹 보기를 열 때 messenger_extensions 매개변수가 true로 설정되었는지 확인하세요. 사용자가 공유된 메시지를 통해 웹 보기를 열었을 경우 봇과 통신하지 않아도 Messenger 확장 기능이 작동합니다.
페이지를 호스팅하는 도메인을 화이트리스트에 등록했는지 확인해 보세요.
JS SDK가 확장 기능을 사용하는 모든 페이지에 포함되었는지 확인해 보세요.
SDK가 읽어들이는 작업을 완료하기 전에는 함수를 호출하지 않도록 하세요. window.extAsyncInit (여기에 설명)를 사용하여 읽어들이기가 끝난 시점을 알립니다.
페이지가 https를 통해 제공되고 표준이 아닌 포트는 포함하지 않도록 하세요.