웹/자바스크립트의 주제 메시징

FCM 주제 메시징을 사용하면 게시/구독 모델을 기반으로 특정 주제를 구독하는 여러 기기에 메시지를 보낼 수 있습니다. 필요에 따라 주제 메시지를 작성하면 FCM에서 라우팅을 처리하여 올바른 기기에 정확히 전달합니다.

예를 들어, 지역 조수 예보 앱 사용자는 '조류 특보' 주제를 구독하여 해당 지역에서 최적의 바다 낚시 상태 알림을 수신할 수 있습니다. 스포츠 앱 사용자는 응원하는 팀의 경기 점수 실황을 자동 업데이트로 수신하도록 구독할 수 있습니다.

주제와 관련된 주의사항은 다음과 같습니다.

  • 주제 메시징에서 각 앱에 지원하는 주제 및 구독에는 제한이 없습니다.
  • 주제 메시징은 뉴스, 날씨 등 공개적으로 제공되는 정보에 가장 적합합니다.
  • 주제 메시지는 지연 시간이 아닌 처리량을 위주로 최적화됩니다. 기기 한 대나 적은 수의 기기에 빠르고 안전하게 전달하려면 주제가 아닌 등록 토큰으로 메시지를 타겟팅하세요.
  • 사용자를 기준으로 여러 기기에 메시지를 보내야 하는 경우 해당 사용 사례에 기기 그룹 메시징을 사용하세요.

클라이언트 앱에서 주제 구독

등록 토큰과 주제 이름이 주어지면 Google Instance ID server API를 사용하여 주제에 토큰을 추가할 수 있습니다. 이 엔드포인트에서 Instance ID API를 호출하면서 앱 인스턴스의 등록 토큰과 주제 이름을 제공하면 됩니다.

 https://iid.googleapis.com/iid/v1/<REGISTRATION_TOKEN>/rel/topics/<TOPIC_NAME>

예를 들어 앱 인스턴스에서 'movies'라는 주제를 구독하려면 아래와 같이 엔드포인트에 POST 요청을 전송하면서 인증 헤더에 서버 API 키를 추가합니다.

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

서버 키는 기밀 정보이므로 어떠한 경우에도 클라이언트에서 이러한 유형의 요청을 전송하지 마세요.

요청에 성공하면 HTTP 200 OK가 반환됩니다. 오류 응답 및 일괄 요청 전송에 관한 자세한 내용은 앱 인스턴스의 관계 맵 만들기를 참조하세요.

주제 메시지 수신 및 처리

FCM은 다른 다운스트림 메시지와 동일한 방식으로 주제 메시지를 전송합니다. 클라이언트에서 메시지를 처리하는 방법은 웹페이지의 포그라운드/백그라운드 상태 및 이 섹션에서 설명하는 기타 요소에 따라 다릅니다.

메시지의 동작은 페이지가 포커스를 갖는 포그라운드 상태인지, 백그라운드 상태인지, 다른 탭 뒤에 숨겨져 있는지, 완전히 닫혀 있는지에 따라 다릅니다. 어떠한 경우든 페이지는 onMessage 콜백을 처리해야 하지만, 백그라운드 상태인 경우에는 사용자가 웹 앱을 포그라운드로 전환할 수 있도록 setBackgroundMessageHandler를 처리하거나 디스플레이 알림을 구성해야 할 수도 있습니다.

앱 상태 알림 데이터 모두
포그라운드 onMessage onMessage onMessage
백그라운드(서비스 워커) SDK가 표시하는 알림 setBackgroundMessageHandler SDK가 표시하는 알림

웹 앱이 포그라운드 상태일 때 메시지 처리

onMessage 이벤트를 수신하려면 앱에서 firebase-messaging-sw.js에 Firebase 메시징 서비스 워커를 정의해야 합니다. useServiceWorker를 사용하여 기존 서비스 워커를 지정할 수도 있습니다.

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here, other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in the
// messagingSenderId.
firebase.initializeApp({
  'messagingSenderId': 'YOUR-SENDER-ID'
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();

앱이 포그라운드 상태일 때, 즉 사용자가 현재 웹페이지를 보고 있을 때는 데이터 및 알림 페이로드를 페이지에서 직접 수신할 수 있습니다.

// Handle incoming messages. Called when:
// - a message is received while the app has focus
// - the user clicks on an app notification created by a service worker
//   `messaging.setBackgroundMessageHandler` handler.
messaging.onMessage(function(payload) {
  console.log('Message received. ', payload);
  // ...
});

웹 앱이 백그라운드 상태일 때 메시지 처리

앱이 백그라운드 상태일 때 수신된 모든 메시지는 브라우저의 디스플레이 알림을 트리거합니다. 앱 서버의 전송 요청이나 클라이언트의 서비스 워커 로직을 사용하여 제목, 클릭 동작 등의 알림 관련 옵션을 지정할 수 있습니다.

전송 요청에 알림 옵션 설정

앱 서버에서 알림 메시지를 전송하는 경우 FCM JavaScript API는 click_action 키를 지원합니다. 일반적으로 이 키는 웹 앱의 페이지로 설정되므로 사용자가 알림을 클릭하면 앱이 포그라운드로 전환됩니다.

https://fcm.googleapis.com/fcm/send
Content-Type: application/json
Authorization: key=AIzaSyC...akjgSX0e4

{ "notification": {
    "title": "Background Message Title",
    "body": "Background message body",
    "click_action" : "https://dummypage.com"
  },

  "to" : "/topics/matchday"

}

데이터 메시지는 click_action을 지원하지 않으므로 모든 데이터 메시지에 알림 페이로드를 추가하는 것이 좋습니다. 서비스 워커를 사용하여 알림을 처리할 수도 있습니다.

알림과 데이터 메시지의 차이점에 대한 설명은 메시지 유형을 참조하세요.

서비스 워커에서 알림 옵션 설정

알림 메시지와 데이터 메시지 모두에 대해 서비스 워커에서 알림 옵션을 설정할 수 있습니다. 우선 서비스 워커에서 앱을 초기화합니다.

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here, other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in the
// messagingSenderId.
firebase.initializeApp({
  'messagingSenderId': 'YOUR-SENDER-ID'
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();

옵션을 설정하려면 firebase-messaging-sw.js에서 setBackgroundMessageHandler를 호출합니다. 이 예에서는 제목, 본문, 아이콘 및 클릭 동작 옵션을 설정합니다.

messaging.setBackgroundMessageHandler(function(payload) {
  console.log('[firebase-messaging-sw.js] Received background message ', payload);
  // Customize notification here
  var notificationTitle = 'Background Message Title';
  var notificationOptions = {
    body: 'Background Message body.',
    icon: '/firebase-logo.png'
  };

  return self.registration.showNotification(notificationTitle,
    notificationOptions);
});

보내기 요청 작성

서버 쪽에서 Firebase 클라우드 메시징 주제로 메시지를 보내는 것은 개별 기기나 사용자 그룹으로 메시지를 보내는 것과 매우 비슷합니다. 앱 서버는 to 키를 /topics/yourTopic 등의 값으로 설정합니다. 개발자는 다음 정규 표현식과 일치하는 모든 주제 이름을 선택할 수 있습니다. "/topics/[a-zA-Z0-9-_.~%]+"

주제 HTTP POST 요청

주제 1개로 보내는 방법은 다음과 같습니다.

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
  "to" : "/topics/foo-bar",
  "priority" : "high",
  "notification" : {
    "body" : "This is a Firebase Cloud Messaging Topic Message!",
    "title" : "FCM Message",
  }
}

주제 HTTP 응답

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

주제 XMPP 메시지

주제 1개로 보내는 방법은 다음과 같습니다.

<message id="">
  <gcm xmlns="google:mobile:data">
{
  "to" : "/topics/foo-bar",
  "priority" : "high",
  "notification" : {
    "body" : "This is a Firebase Cloud Messaging Topic Message!",
    "title" : "FCM Message",
  }
}
  </gcm>
</message>

주제 XMPP 응답

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

다음 단계

다음에 대한 의견 보내기...

도움이 필요하시나요? 지원 페이지를 방문하세요.