콘솔로 이동

자바스크립트 클라이언트에서 메시지 수신

메시지 동작은 페이지가 포커스를 갖는 포그라운드 상태인지, 백그라운드 상태인지, 다른 탭 뒤에 숨겨져 있는지 또는 완전히 닫혀 있는지에 따라 다릅니다. 어떠한 경우든 페이지는 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는 fcm_options.link 키를 지원합니다. 일반적으로 이 키는 웹 앱의 페이지로 설정됩니다.

https://fcm.googleapis.com//v1/projects/<YOUR-PROJECT-ID>/messages:send
Content-Type: application/json
Authorization: bearer <YOUR-ACCESS-TOKEN>

{
  "message": {
    "token": "eEz-Q2sG8nQ:APA91bHJQRT0JJ..."
    "notification": {
      "title": "Background Message Title",
      "body": "Background message body"
    },
    "webpush": {
      "fcm_options": {
        "link": "https://dummypage.com"
      }
    }
  }
}

링크 값이 브라우저 탭에 이미 열려 있는 페이지를 가리키면 알림을 클릭할 때 해당 탭이 포그라운드로 전환됩니다. 페이지가 열려 있지 않은 경우 알림을 클릭하면 새 탭에서 페이지가 열립니다.

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

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

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

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

// 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);
});

알림 권장사항

웹에서 푸시 메시지를 다루는 데 익숙하다면 좋은 알림 시스템의 조건에 관한 대략적인 가이드를 읽어 보셨을 것이라고 생각합니다. 웹용 FCM을 통해 알림을 전송하려는 개발자가 가장 중요하게 고려할 사항은 정확성과 관련성입니다. 알림의 정확성과 관련성을 유지하기 위해 구체적으로 다음과 같은 사항이 권장됩니다.

  • 아이콘 필드를 사용하여 의미 있는 이미지를 전송하세요. 대체로 이 이미지는 사용자가 바로 알아볼 수 있는 회사 또는 앱 로고여야 합니다. 채팅 애플리케이션이라면 사용자의 프로필 이미지일 수도 있습니다.
  • 제목 필드를 사용하여 메시지의 성격을 정확히 표현하세요. 예를 들어 '재영님의 회신'은 '새 메시지'보다 정확한 정보를 전해 줍니다. 이 귀중한 공간에 회사 이름이나 앱 이름을 넣지 마세요. 해당 목적으로는 아이콘이 적합합니다.
  • 알림 제목 또는 본문을 사용하여 웹사이트 이름 또는 도메인을 표시하지 마세요. 알림에 이미 도메인 이름이 포함됩니다.
  • fcm_options.link를 추가하세요. 일반적인 용도는 사용자가 웹 앱을 브라우저에 다시 띄우도록 하는 것입니다. 드문 경우지만 전달해야 하는 정보가 알림 창에 모두 표시되는 경우에는 링크가 필요하지 않을 수도 있습니다.