Menerima pesan di klien JavaScript

Perilaku pesan berbeda-beda, tergantung pada apakah halaman berada di latar depan (memiliki fokus), di latar belakang, tersembunyi di balik tab lain, atau tertutup sepenuhnya. Dalam semua kasus, halaman harus menangani callback onMessage. Namun dalam kasus latar belakang, Anda mungkin juga harus menangani onBackgroundMessage atau mengonfigurasi notifikasi tampilan agar pengguna dapat memindahkan aplikasi web Anda ke latar depan.

Status aplikasi	Notifikasi	Data	Keduanya
Latar depan	onMessage	onMessage	onMessage
Latar belakang (pekerja layanan)	onBackgroundMessage (notifikasi tampilan otomatis ditampilkan)	onBackgroundMessage	onBackgroundMessage (notifikasi tampilan otomatis ditampilkan)

Contoh panduan memulai JavaScript mendemonstrasikan semua kode yang dibutuhkan untuk menerima pesan.

Penting: Panduan ini menyebutkan inisialisasi Firebase di service worker. Untuk menggunakan SDK modular di service worker, Anda harus memaketkan file service worker, karena modul ES relatif baru dan tidak didukung secara luas (Lihat Modul ES di sservice worker). Jika tidak ingin memaketkan file service worker, Anda dapat menggunakan API namespaced yang disediakan oleh paket kompatibilitas. Untuk melihat cara menggunakan pemaket modul dengan Firebase, baca artikel Menggunakan pemaket modul dengan Firebase.

Menangani pesan saat aplikasi web ada di latar depan

Untuk menerima peristiwa onMessage, aplikasi Anda harus menentukan pekerja layanan pesan Firebase dalam firebase-messaging-sw.js. Sebagai alternatif, Anda dapat memberikan pekerja layanan yang ada ke SDK melalui getToken(): Promise<string>.

Web

Pelajari lebih lanjut Web API modular yang dapat di-tree-shaking dan upgrade dari API namespace.

import { initializeApp } from "firebase/app";
import { getMessaging } from "firebase/messaging/sw";

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
const firebaseApp = initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

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

Web

// 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.
// Replace 10.13.2 with latest version of the Firebase JS SDK.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.js');

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

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

Ketika aplikasi Anda ada di latar depan (pengguna sedang melihat halaman web Anda), Anda dapat menerima payload data dan notifikasi secara langsung di halaman.

Web

Pelajari lebih lanjut Web API modular yang dapat di-tree-shaking dan upgrade dari API namespace.

// 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.onBackgroundMessage` handler.
import { getMessaging, onMessage } from "firebase/messaging";

const messaging = getMessaging();
onMessage(messaging, (payload) => {
  console.log('Message received. ', payload);
  // ...
});
messaging_receive_message.js

Web

// 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.onBackgroundMessage` handler.
messaging.onMessage((payload) => {
  console.log('Message received. ', payload);
  // ...
});
index.js

Menangani pesan saat aplikasi web ada di latar belakang

Semua pesan yang diterima saat aplikasi ada di latar belakang memicu notifikasi tampilan di browser. Anda dapat menentukan opsi untuk notifikasi ini, seperti judul atau tindakan klik, baik dalam permintaan kirim dari server aplikasi Anda maupun menggunakan logika pekerja layanan pada klien.

Tindakan klik hanya mendukung URL HTTPS yang aman.

Menyetel opsi notifikasi dalam permintaan kirim

Untuk pesan notifikasi yang dikirim dari server aplikasi, FCM JavaScript API mendukung kunci fcm_options.link. Biasanya kunci ini disetel ke halaman dalam aplikasi web Anda:

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

Jika nilai link menunjuk ke halaman yang sudah terbuka di tab browser, klik pada notifikasi akan membawa tab tersebut ke latar depan. Jika halaman belum terbuka, klik pada notifikasi akan membuka halaman di tab baru.

Karena pesan data tidak mendukung fcm_options.link, sebaiknya Anda menambahkan payload notifikasi ke semua pesan data. Atau, Anda dapat menangani notifikasi menggunakan pekerja layanan.

Penjelasan mengenai perbedaan antara pesan notifikasi dan pesan data dapat dibaca di bagian Jenis pesan.

Catatan: Untuk mengirim pesan ke topik, gunakan Admin SDK untuk membuat instance aplikasi berlangganan topik. Untuk menggunakan Admin FCM API, Anda harus terlebih dahulu mengikuti langkah-langkah di artikel Menambahkan Firebase Admin SDK ke Server untuk menginisialisasi SDK tersebut.

Menetapkan opsi notifikasi dalam pekerja layanan

Untuk pesan data, Anda dapat menyetel opsi notifikasi di pekerja layanan. Pertama, inisialisasi aplikasi Anda dalam pekerja layanan:

Web

Pelajari lebih lanjut Web API modular yang dapat di-tree-shaking dan upgrade dari API namespace.

import { initializeApp } from "firebase/app";
import { getMessaging } from "firebase/messaging/sw";

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
const firebaseApp = initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

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

Web

// 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.
// Replace 10.13.2 with latest version of the Firebase JS SDK.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.js');

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

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

Untuk menyetel opsi, panggil onBackgroundMessage di firebase-messaging-sw.js. Dalam contoh ini, kita membuat notifikasi dengan kolom judul, isi, dan ikon.

Web

Pelajari lebih lanjut Web API modular yang dapat di-tree-shaking dan upgrade dari API namespace.

import { getMessaging } from "firebase/messaging/sw";
import { onBackgroundMessage } from "firebase/messaging/sw";

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

  self.registration.showNotification(notificationTitle,
    notificationOptions);
});
messaging_on_background_message.js

Web

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

  self.registration.showNotification(notificationTitle, notificationOptions);
});
service-worker.js

Catatan: Jika Anda ingin menentukan perilaku kustom di service worker saat notifikasi diklik, pastikan untuk menangani notificationclick sebelum mengimpor fungsi atau library FCM. Jika tidak, FCM mungkin akan mengganti perilaku kustom.

Praktik terbaik untuk notifikasi

Jika sudah terbiasa menggunakan pesan push untuk web, Anda mungkin sudah membaca panduan umum mengenai kriteria notifikasi yang bagus. Untuk developer yang mengirimkan notifikasi melalui FCM untuk Web, pertimbangan yang paling penting adalah ketepatan dan relevansi. Berikut adalah beberapa rekomendasi khusus untuk menjaga notifikasi Anda tetap tepat dan relevan:

• Gunakan kolom ikon untuk mengirim gambar yang bermakna. Sering kali, gambar bermakna adalah logo perusahaan atau logo aplikasi yang dapat langsung dikenali pengguna. Atau, untuk aplikasi chat, gambar tersebut mungkin gambar profil pengguna yang mengirim.
• Gunakan kolom judul untuk mengungkapkan secara tepat sifat pesan yang diterima. Misalnya, "Jimmy menjawab" menyampaikan informasi yang lebih tepat daripada "Pesan baru". Jangan gunakan ruang berharga ini untuk nama perusahaan atau nama aplikasi Anda — sebaiknya gunakan ikon saja untuk keperluan itu.
• Jangan gunakan judul atau isi notifikasi untuk menampilkan nama situs atau domain; notifikasi sudah berisi nama domain Anda.
• Tambahkan fcm_options.link, biasanya untuk menghubungkan pengguna kembali ke aplikasi web Anda dan menjadikannya sebagai fokus pada browser. Terkadang, meskipun sangat jarang terjadi, jika semua informasi yang perlu Anda sampaikan sudah masuk ke dalam notifikasi, Anda tidak memerlukan link.