Notifikasi browser (Web Push)
Aktifkan notifikasi di browser pengunjung dan kirim uji coba. Izin pengunjung, berkas di situs, dan kunci VAPID.
Di halaman ini
Web Push menampilkan notifikasi melalui browser. Pengunjung situs dengan widget harus mengizinkannya terlebih dahulu. Fitur ini berbeda dari ikon lonceng dan notifikasi untuk operator di ruang kerja.
Langkah 1. Pasang service worker di domain Anda
Minta pengelola situs memasang berkas mybot-sw.js. Tanpanya, browser tidak dapat menerima dan menampilkan notifikasi.
Service worker adalah skrip kecil yang dipakai browser untuk menerima notifikasi. Berkas ini harus berada di situs Anda: skrip dari domain GetMyBot tidak dapat mengendalikan notifikasi domain Anda. Alamat situs lengkap dengan protokol tetapi tanpa jalur halaman disebut origin, misalnya https://example.com.
-
Di ruang kerja, buka Widget → Web Push dan unduh
mybot-sw.js. -
Pasang berkas di akar setiap origin yang memakai widget, tepat pada alamat seperti berikut:
https://example.com/mybot-sw.js https://shop.example.com/mybot-sw.jsPengaturan Web Push menampilkan alamat yang diharapkan untuk setiap tautan notifikasi yang diizinkan. Buka alamat tersebut di browser untuk memastikan berkasnya tersedia.
-
Saat alamat berkas dibuka, browser harus menerima JavaScript melalui HTTPS, bukan halaman situs. Jika yang muncul halaman biasa,
404, atau pengalihan ke alamat lain, langganan tidak akan bekerja. Pada aplikasi satu halaman atau situs yang memakai CDN, periksa khususnya agar alamat tersebut tidak mengembalikanindex.html. -
Setelah platform diperbarui, unggah kembali berkas seperti sumber statis lain. Perubahan pengaturan Web Push atau pergantian kunci tidak mengharuskan pemasangan ulang berkas.
Jalur berkas harus tepat: widget hanya mendaftarkan atau memakai ulang worker di /mybot-sw.js. Dua parameter publik untuk pengaturan rute, mb_key dan mb_api, ditambahkan otomatis; jangan menambahkannya sendiri.
Jika Anda mendaftarkan worker sendiri
Jika Anda perlu mengatur pendaftaran atau membatasi alamat yang dapat dibuka setelah notifikasi diklik, daftarkan berkas melalui kode situs:
navigator.serviceWorker.register("/mybot-sw.js?nav=https://shop.example.com");
Parameter nav dapat memuat hingga 8 HTTPS-origin yang tepat, dipisahkan koma. Worker memeriksa tujuan klik terhadap daftar ini dan origin-nya sendiri, terpisah dari daftar server pada langkah 2. Jika widget menemukan pendaftaran tersebut, nilai nav Anda dipertahankan.
Jika situs sudah memiliki service worker
Widget tidak pernah mengganti service worker lain karena hal itu dapat merusak situs. Berlangganan lewat worker lain juga tidak akan memasang penangan notifikasi dan klik dari GetMyBot. Jika halaman sudah dikendalikan worker lain, percobaan berlangganan akan dianggap “tidak tersedia”. Pasang mybot-sw.js di situs tanpa worker lain pada cakupan akar, atau hubungi dukungan sebelum mencoba menggabungkan dua worker.
Langkah 2. Aktifkan Web Push untuk bot
Web Push diatur pada halaman Widget, bersama pengaturan saluran situs lainnya. Ada dua kolom wajib:
- Kontak VAPID: alamat
mailto:atau tautan HTTPS yang dapat dipakai layanan push untuk memberi tahu Anda jika pengiriman bermasalah, misalnyamailto:help@example.com. - Tautan notifikasi yang diizinkan: satu HTTPS-origin per baris. Klik notifikasi hanya boleh membuka jalur relatif pada situs Anda atau salah satu origin tepat dalam daftar ini. Daftar ini wajib diisi; notifikasi dengan tujuan lain ditolak sebelum dikirim.
Saat pertama kali disimpan, server membuat sepasang kunci VAPID. Pengaturan menampilkan kunci publik untuk browser. Kunci privat tetap berada di server dan tidak dikembalikan oleh API mana pun.
Jam tenang (dijelaskan di bawah) dapat diatur melalui API, tetapi belum memiliki kolom pada halaman ini.
Langkah 3. Dapatkan izin dari pengunjung
Pengunjung harus memberi izin sendiri. Membuka halaman saja tidak mendaftarkannya:
- Permintaan izin browser hanya muncul setelah pengunjung menekan tombol notifikasi pada widget.
- Orang yang belum pernah menekan tombol tidak melihat kesalahan. Jika browser tidak mendukung push atau izin sudah ditolak, tombol disembunyikan sampai percobaan pertama.
- Memuat widget hanya memperbarui izin yang sudah diberikan. Pemuatan ini tidak memunculkan permintaan izin, tidak memasang worker, dan tidak membuat langganan baru.
- Penolakan disimpan untuk waktu lama dan tetap berlaku setelah halaman dimuat ulang, walaupun browser masih menyimpan objek langganannya.
Setelah widget dimuat, kode situs Anda juga dapat memanggil dua tindakan berikut:
await window.mybot.push.subscribe(); // minta izin dan daftarkan langganan
await window.mybot.push.unsubscribe(); // cabut di server dan browser
Status langganan: subscribed (aktif), revoked (pengunjung berhenti berlangganan), atau expired (alamat pengiriman tidak berfungsi lagi). Ruang kerja dan API menampilkan jenis browser, bahasa, zona waktu, status, serta tanggal. Alamat pengiriman dan kunci enkripsi disimpan di server dalam bentuk terenkripsi. Setelah disimpan, keduanya tidak ditampilkan kepada pemilik bot dan tidak dikembalikan melalui API atau MCP.
Mengirim notifikasi uji
Bagian uji mengirim satu pesan ke browser yang terakhir berlangganan. Tiga syarat harus terpenuhi:
- Web Push aktif untuk bot;
- setidaknya satu langganan berstatus
subscribed; - ada satu dokumen jenis Push yang sudah diterbitkan di Studio konten. Uji mengacu pada versi dokumen yang tepat, seperti pop-up atau kampanye.
Setelah uji dimulai, ruang kerja langsung menerima nomor pesan, sedangkan pengiriman berlanjut di latar belakang. Pemilihan audiens, jadwal, dan penghentian pengiriman belum tersedia pada halaman mana pun.
Batas isi notifikasi
Jika satu saja batas di bawah dilanggar, server menolak seluruh pengiriman. Isi tidak dipotong diam-diam.
| Kolom | Batas |
|---|---|
title | Wajib, 1–120 karakter |
body | Wajib, 1–512 karakter |
tag | Opsional, maksimal 128 karakter |
actions | Maksimal 2; ID dan teks tiap tindakan 1–64 karakter, tanpa duplikat |
icon_url, image_url | Hanya HTTPS, tanpa informasi pengguna dan fragmen alamat |
navigation | Jalur relatif yang diawali /, atau salah satu origin yang tepat diizinkan |
data | Hanya kunci action, campaign_id, content_id, experiment_id, message_id; tiap nilai maksimal 256 karakter |
| Seluruh data notifikasi | Maksimal 3 KiB |
Nilai data ditolak jika memuat bearer , secret, password, token=, atau tanda @. Dengan demikian, nilai profil atau token akses tidak dapat dikirim melalui notifikasi. Data dengan receipt_signature buatan sendiri juga ditolak; server menambahkan nilai teknis itu saat pengiriman.
Server dan worker sama-sama menganggap tautan seperti //host/path atau tautan dengan garis miring terbalik sebagai origin lain, bukan jalur relatif.
Jam tenang
Jam tenang menentukan rentang waktu setempat ketika pengiriman ditunda, bukan dibatalkan. Pesan dikirim pada saat pertama yang diizinkan. Zona waktu diambil dari penerima saat berlangganan; jika tidak ada, zona waktu bot dipakai. Jika jam akhir lebih awal dari jam mulai, rentang berlanjut melewati tengah malam. Waktu yang tidak ada karena perubahan jam musiman digeser ke waktu berikutnya yang berlaku.
Jam tenang merupakan bagian dari pengaturan Web Push dan dapat diisi melalui REST API pada kolom quiet_hours. Editornya belum tersedia di ruang kerja.
Pengiriman, pengulangan, dan tanda terima
- Pekerja latar belakang mengambil pesan, menahannya selama pengiriman, dan mencoba lagi paling banyak 8 kali atau selama 24 jam, mana yang lebih dulu tercapai.
- Jawaban
429dari layanan push diulang menurutRetry-After, paling lama 24 jam. Waktu tunggu dan jawaban5xxdiulang dengan jeda yang berubah-ubah. Jawaban4xxlainnya mengakhiri percobaan. - Jawaban
404atau410berarti langganan browser sudah tidak ada. Statusnya menjadiexpireddan tidak dicoba lagi. - Service worker mengirim dua tanda terima:
clickketika pengunjung membuka notifikasi, dancloseketika menutupnya. Keduanya ditandatangani dan terkait dengan satu pesan serta satu langganan, sehingga tidak dapat dipalsukan atau dipakai ulang untuk pesan lain. - Laporan pengaturan menghitung langganan menurut status dan jumlah notifikasi yang dibuka. Secara internal dicatat peristiwa
accepted,sent,failed,expired,clicked, danclosed; semuanya juga masuk ke riwayat pelanggan pada bagian Orang.
Isi jawaban dari layanan push tidak disimpan. Jika pengiriman gagal, hanya kode alasan dari daftar terbatas yang tersisa.
Mengganti kunci VAPID
Mengganti kunci VAPID menonaktifkan semua langganan saat ini. Karena itu, ruang kerja menampilkan jumlah browser yang terkena dampak dan meminta konfirmasi. Secara teknis, permintaan pertama mengembalikan 409 beserta jumlah langganan aktif. Setelah dikonfirmasi, pasangan kunci baru dibuat dan langganan lama tidak berlaku. Setiap pengunjung harus mengizinkan notifikasi lagi karena langganan browser terikat pada kunci lama.
Widget mengenali keadaan ini: pada izin jelas berikutnya dari pengunjung, langganan dengan kunci lama dibuang dan dibuat lagi, bukan dibiarkan tidak berfungsi.
Batas keamanan
Informasi ini dapat diberikan kepada tim keamanan situs:
- GetMyBot hanya mengirim ke alamat HTTPS publik pada port 443. Alamat loopback, privat, link-local, multicast, dan CGNAT ditolak. Jika nama domain menunjuk ke beberapa alamat, semuanya harus publik.
- Nama domain diperiksa ulang pada setiap pengiriman dan koneksi hanya dibuat ke alamat yang sudah diperiksa. Pengalihan alamat tidak diikuti dan ukuran jawaban dibatasi.
- Alamat langganan yang sama dikenali dari sidik jari dalam satu akun. Satu bot tidak dapat mengetahui apakah browser berlangganan ke bot lain.
- Rute browser berada di luar
/api, pada area widget. Setiap permintaan memeriksa kembali kunci widget bertanda tangan, sesi widget, serta origin halaman yang tepat, dan memakai batas permintaan yang sama dengan widget.
Data dan masa penyimpanan
Langganan browser dan pesan termasuk kategori penyimpanan push, dengan masa bawaan 180 hari. Data ini ikut dalam penggabungan profil pelanggan, ekspor, dan penghapusan data pribadi seperti data pelanggan lainnya.
Dukungan browser dan pemeriksaan masalah
Browser harus mendukung notifikasi, service worker, dan Push API sekaligus. Chrome, Edge, dan Firefox versi terkini pada komputer dan Android mendukungnya. Di iOS, Safari menyediakan Web Push hanya untuk situs yang ditambahkan pengunjung ke layar utama.
Jika notifikasi tidak datang:
- Buka
https://situs-anda/mybot-sw.jsdi browser. Pastikan yang muncul skrip, bukan404, pengalihan, atau halaman HTML. - Periksa apakah origin halaman ada dalam daftar origin widget yang diizinkan dan tujuan notifikasi juga diizinkan.
- Pastikan pengunjung benar-benar memberi izin dan halaman tidak dikendalikan service worker lain.
- Setelah kunci diganti, minta semua pengunjung berlangganan lagi.
- Jika uji pengiriman tidak tersedia, periksa apakah ada browser yang berlangganan dan dokumen Push yang sudah diterbitkan.
API dan MCP
Operasi pengelolaan tersedia dengan token personal; lihat REST API dan token. Membaca memerlukan scope web_push:read dan hak web_push.read pada bot. Mengubah memerlukan web_push:write dan web_push.write; pengaktifan juga memerlukan integrations.secrets. MCP memiliki empat alat baca saja, termasuk daftar langganan; lihat MCP.
Langkah berikutnya
- Widget di situs: memasang dan memeriksa widget.
- Studio konten: dokumen Push yang dipakai saat mengirim.
- SDK pelanggan: konten dan chat serupa di aplikasi seluler.