Panduan Integrasi Web SDK Versi Chrome Extension (untuk V3)

Catatan: Dokumen ini adalah panduan integrasi standar untuk MTpush Web SDK di lingkungan Chrome extension (Manifest V3), hanya berlaku untuk browser yang mendukung arsitektur ekstensi V3.

1. Pengenalan Produk

MTpush Web SDK - Versi Chrome Extension adalah alat integrasi push khusus untuk pengembang Chrome extension (Manifest V3). SDK ini memanfaatkan notifikasi sistem Chrome dan koneksi persisten Service Worker untuk memberikan layanan push yang stabil dan efisien bagi ekstensi.

SDK ini hanya mendukung browser Chrome dan browser berbasis Chromium (seperti Edge Chromium), serta membutuhkan lingkungan runtime ekstensi browser. Tidak diperlukan otorisasi tambahan dari pengguna; ekstensi dapat langsung menerima notifikasi push setelah proses inisialisasi selesai.

📦 Fitur Utama

• Notifikasi sistem: Menampilkan pesan push langsung melalui pusat notifikasi browser
• Integrasi khusus ekstensi: Disesuaikan dengan arsitektur Chrome extension, berlangganan otomatis tanpa interaksi pengguna
• Akses ringan: API terpadu untuk inisialisasi dan penerimaan pesan secara cepat
• Dukungan pesan kustom: Penargetan pengguna fleksibel melalui tag, alias, dan lainnya

📌 Skenario Penggunaan

• Mengirim pengingat, promosi, pembaruan, dan notifikasi lain ke pengguna ekstensi
• Pengiriman informasi real-time penting, seperti status logistik dan pesan aktivitas
• Membangun ekstensi utilitas browser dengan kemampuan pengiriman pesan

2. Isi Paket SDK

              
              webPushSdk.min.x.x.x-release.zip
├── chrome-extension
│   ├── webSdkExtension.min.x.x.x.js     // File utama SDK
│   ├── swExtension.min.x.x.x.js         // File Service Worker
│   └── push-demo                        // Proyek contoh Chrome extension

            

3. Proses Integrasi

1. Dapatkan Informasi Aplikasi

Buat aplikasi baru di konsol EngageLab. Setelah berhasil, sistem akan otomatis menghasilkan AppKey sebagai identitas aplikasi. Detail: Dokumen Pengaturan Aplikasi

2. Integrasi ID Ekstensi

• Dapatkan ID ekstensi Chrome Anda;
• Masuk ke konsol EngageLab WebPush, buka [Pengaturan Integrasi] - [Integrasi Chrome Extension], lalu isi nama dan ID ekstensi.

Gambar ilustrasi:

3. Akses SDK

Langkah 1: Unduh SDK dan atur ekstensi

Atur konfigurasi berikut pada manifest.json:

              
              {
  "manifest_version": 3,
  "permissions": [
    "storage",
    "notifications",
    "tabs",
    "activeTab"
  ],
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["webSdkExtension.min.x.x.x.js"],
      "run_at": "document_end"
    },
    {
      "matches": ["<all_urls>"],
      "js": ["init-sdk.js"],
      "run_at": "document_end"
    }
  ],
  "background": {
    "service_worker": "swExtension.min.x.x.x.js"
  }
}

            

Setelah mengimpor webSdkExtension.min.x.x.x.js, Anda dapat memanggil metode SDK melalui window.MTpushInterfaceExtension.

Langkah 2: Hasilkan user_str

Disarankan menggunakan fingerprint browser untuk menghasilkan user_str unik agar mencegah pendaftaran pengguna tidak valid:

              
              // Contoh kode mengambil fingerprint Canvas, WebGL, extension (kode tidak diubah)
const visitorId = getFingerprint();
console.log('user_str', visitorId);

            

Langkah 3: Inisialisasi SDK

              
              if (window.MTpushInterfaceExtension) {
  window.MTpushInterfaceExtension.initSdk({
    appkey: '',      // AppKey dari konsol
    user_str: '',    // Fingerprint browser atau pengenal unik pengguna login
  });
}

chrome.runtime.onMessage.addListener((message) => {
  switch (message.type) {
    case 'MTPUSH_INIT_SDK_SUCCESS':
      console.log('Inisialisasi SDK berhasil:', message.data);
      break;
    case 'MTPUSH_INIT_SDK_FAIL':
      console.log('Inisialisasi SDK gagal:', message.data);
      break;
    case 'MTPUSH_ON_MSG_RECEIVE':
      console.log('Pesan push diterima:', message.data);
      break;
  }
});

            

MTPUSH_ON_MSG_RECEIVE akan dipicu saat pesan push diterima, dan hanya berlaku untuk halaman berikut:

1. Halaman yang baru dibuka setelah ekstensi diinstal (atau setelah ekstensi dimulai ulang);
2. Halaman yang saat ini berada di tampilan latar depan.

4. Catatan

1. Inisialisasi SDK harus dilakukan di halaman yang "baru dibuka setelah ekstensi diinstal"; halaman lama tidak dapat membangun koneksi.
2. Jika ekstensi dinonaktifkan atau dihapus, maka tidak akan dapat menerima push apa pun.
3. Setelah ekstensi diaktifkan atau dimuat ulang, halaman mana pun harus dibuka ulang untuk proses inisialisasi dan langganan.
4. Dalam browser yang sama, meskipun menggunakan AppKey yang sama, ekstensi atau user_str yang berbeda akan dianggap sebagai pengguna berbeda.
5. Ekstensi tidak memerlukan otorisasi pengguna untuk izin notifikasi; akan otomatis berlangganan notifikasi sistem setelah inisialisasi berhasil.

5. API Lanjutan

Untuk penggunaan antarmuka SDK lebih lanjut, silakan lihat dokumen resmi: Web SDK API

6. Menjalankan Demo

Paket kompresi mencakup proyek contoh Chrome extension push-demo, yang dapat digunakan untuk pengujian fungsi push secara cepat:

1. Ganti direktori lib dengan SDK terbaru;
2. Atur appkey dan user_str yang benar di init-sdk.js;
3. Buka chrome://extensions, aktifkan mode pengembang, lalu impor demo yang telah diekstrak;
4. Buka halaman web apa saja untuk menyelesaikan proses inisialisasi dan langganan;
5. Masuk ke konsol EngageLab dan kirim pesan uji coba;
6. Klik ikon Push di kanan bawah halaman web untuk melihat regid, catatan push, serta mengatur tag/alias;
7. Jika Chrome menampilkan error seperti "session timeout", ekstensi akan otomatis melakukan langganan ulang.