API Web SDK

Autentikasi

Saat pengembang melakukan inisialisasi, perlu memasukkan informasi yang dibutuhkan. Struktur data ini dihasilkan oleh server pengembang dan dikirim ke browser, digunakan untuk inisialisasi MTpush yang telah diotorisasi agar dapat berjalan di browser. Pengembang harus memastikan hanya pengguna sah yang dapat memanggil dan memperoleh data ini.

Struktur Data Inisialisasi

interface MTInitInfo { website_push_id: string; code: number; master_secret: string; passwd: string; pull: number; regid: string; sess: string; tagalias: number; uid: number; vapid_pubkey: string; } type dataType = { code: number, content: string, message: string, }; interface InitType { report_url?: string; // Report URL, used for private cloud or custom deployments baseUrl?: string; // Server domain; when used together with report_url, the private cloud or custom deployment logic is used userLang?: string; // Defaults to navigator.language and must be a language value supported by the browser safari_url?: string; // Safari push test field appkey: string; // AppKey of the application registered on the EngageLab platform, required user_str: string; // Unique user identifier, required swUrl?: string; // Default: "/sw" + sdkEnv.prefix is_temporary?: "n" | "t"; // Default: "n" debugMode?: boolean; // Default: false webSocketUrl?: string; // If not provided, baseUrl will be used fail?: (data: dataType | undefined) => void; // Initialization failure callback success?: (data: dataType | undefined) => void; // Initialization success callback webPushcallback?: def; canGetInfo?: (d: MTInitInfo) => void; custom?: (Callback: () => void) => void; // Callback for custom prompts; call Callback to request notification permission maOpen?: boolean; // Whether to enable the ma-sdk module maChannel?: string; // Channel name used by ma-sdk; default: default-channel appName?: string; // Website name used by ma-sdk for reporting userIdentity?: { userId?: string; anonymousId?: string }; // User identity used by ma-sdk maCompletion?: (code: number, msg: string) => void; // ma-sdk initialization completion callback openUrl?: string; // Redirect link when clicking a notification encodeSwUrl?: boolean; // Whether to encode swUrl regidSearchPath?: string; // Page path for querying Registration ID }
              
              interface MTInitInfo {
  website_push_id: string;
  code: number;
  master_secret: string;
  passwd: string;
  pull: number;
  regid: string;
  sess: string;
  tagalias: number;
  uid: number;
  vapid_pubkey: string;
}

type dataType = {
  code: number,
  content: string,
  message: string,
};

interface InitType {
  report_url?: string; // Report URL, used for private cloud or custom deployments
  baseUrl?: string; // Server domain; when used together with report_url, the private cloud or custom deployment logic is used
  userLang?: string; // Defaults to navigator.language and must be a language value supported by the browser
  safari_url?: string; // Safari push test field
  appkey: string; // AppKey of the application registered on the EngageLab platform, required
  user_str: string; // Unique user identifier, required
  swUrl?: string; // Default: "/sw" + sdkEnv.prefix
  is_temporary?: "n" | "t"; // Default: "n"
  debugMode?: boolean; // Default: false
  webSocketUrl?: string; // If not provided, baseUrl will be used
  fail?: (data: dataType | undefined) => void; // Initialization failure callback
  success?: (data: dataType | undefined) => void; // Initialization success callback
  webPushcallback?: def;
  canGetInfo?: (d: MTInitInfo) => void;
  custom?: (Callback: () => void) => void; // Callback for custom prompts; call Callback to request notification permission
  maOpen?: boolean; // Whether to enable the ma-sdk module
  maChannel?: string; // Channel name used by ma-sdk; default: default-channel
  appName?: string; // Website name used by ma-sdk for reporting
  userIdentity?: { userId?: string; anonymousId?: string }; // User identity used by ma-sdk
  maCompletion?: (code: number, msg: string) => void; // ma-sdk initialization completion callback
  openUrl?: string; // Redirect link when clicking a notification
  encodeSwUrl?: boolean; // Whether to encode swUrl
  regidSearchPath?: string; // Page path for querying Registration ID
}

            
Tampilkan blok kode ini di jendela mengambang
  • Deskripsi parameter:
    • openUrl: URL yang dibuka saat notifikasi diklik
      • Jika URL tidak ditentukan saat mengirim notifikasi, nilai ini dipakai sebagai tautan redirect;
      • Jika parameter tidak diatur, default redirect ke domain integrasi;
      • Dalam integrasi multi-domain, parameter ini memungkinkan redirect ke URL yang sesuai;
    • encodeSwUrl: Apakah swUrl perlu di-encode
      • Gunakan ketika swUrl berisi karakter khusus (mis. @) dan server membatasi akses ke URL tersebut sehingga pendaftaran Service Worker bisa gagal; tambahkan mekanisme pendaftaran ulang dan encode swUrl saat retry.
    • regidSearchPath: Path halaman untuk menanyakan Registration ID; default /engagelab/regid. Lihat Panduan Pencarian Registration ID.

Hanya satu service worker yang dapat didaftarkan dalam satu scope yang sama. Jika terjadi error saat inisialisasi berhasil seperti "Failed to execute 'subscribe' on 'PushManager': Subscription failed - no active Service Worker," periksa kemungkinan konflik dengan service worker lain. Anda mungkin perlu menggabungkan service worker atau menyelesaikan scope-nya.

Inisialisasi SDK

Deskripsi Antarmuka

Inisialisasi antarmuka.

window.MTpushInterface.init(Object:InitType)
              
              window.MTpushInterface.init(Object:InitType)

            
Tampilkan blok kode ini di jendela mengambang

Deskripsi Parameter

  • Untuk detail, lihat [Deskripsi InitType](/id_ID/docs/web-push/sdk/web-sdk-api#Initialize data structure).
  • Deskripsi data Callback Object:
Nama Parameter Tipe Deskripsi
code number kode return, 0 berarti sukses, selain itu gagal, lihat [kode error](#error code)
message string deskripsi hasil
content string Pesan kegagalan saat registrasi gagal 1003

Contoh Pemanggilan

const appkey = "your_appkey"; const userStr = "adminDemo"; MTpushInterface.init({ appkey: appkey, user_str: userStr, fail(data) { console.log("Online push setup failed", data); }, success(data) { console.log("Online push setup successful", data); }, webPushcallback(code, tip) { console.log("Status code and message", code, tip); }, canGetInfo(data) { // RegId is available here, and initialization config data can also be read from data. console.log("Obtained RegId", MTpushInterface.getRegistrationID(), data); // MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "swefgwwefwfwfwf" }); }, custom: (requestPermission) => { // For custom prompt settings, call requestPermission during an appropriate user action to request notification permission. document.getElementById("subscribe")?.addEventListener("click", () => { if (Notification.permission === "default") { requestPermission(); } else if (Notification.permission === "denied") { console.log("Notification permission is denied and cannot be requested"); } else { console.log("Notification permission has already been granted"); } }); }, });
              
              const appkey = "your_appkey";
const userStr = "adminDemo";

MTpushInterface.init({
  appkey: appkey,
  user_str: userStr,
  fail(data) {
    console.log("Online push setup failed", data);
  },
  success(data) {
    console.log("Online push setup successful", data);
  },
  webPushcallback(code, tip) {
    console.log("Status code and message", code, tip);
  },
  canGetInfo(data) {
    // RegId is available here, and initialization config data can also be read from data.
    console.log("Obtained RegId", MTpushInterface.getRegistrationID(), data);
    // MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "swefgwwefwfwfwf" });
  },
  custom: (requestPermission) => {
    // For custom prompt settings, call requestPermission during an appropriate user action to request notification permission.
    document.getElementById("subscribe")?.addEventListener("click", () => {
      if (Notification.permission === "default") {
        requestPermission();
      } else if (Notification.permission === "denied") {
        console.log("Notification permission is denied and cannot be requested");
      } else {
        console.log("Notification permission has already been granted");
      }
    });
  },
});

            
Tampilkan blok kode ini di jendela mengambang

Mendapatkan RegistrationID

Deskripsi Antarmuka

Panggil API ini untuk mendapatkan RegistrationID sesuai akun saat ini. Nilai hanya dikembalikan setelah inisialisasi sukses, jika tidak akan mengembalikan string kosong. Harus dipanggil setelah callback canGetInfo.

window.MTpushInterface.getRegistrationID()
              
              window.MTpushInterface.getRegistrationID()

            
Tampilkan blok kode ini di jendela mengambang

Contoh Pemanggilan

var rid = window.MTpushInterface.getRegistrationID();
              
              var rid = window.MTpushInterface.getRegistrationID();

            
Tampilkan blok kode ini di jendela mengambang

Hentikan Push

Panggil API ini untuk memutus koneksi push ke backend dan menghentikan penerimaan pesan push.

window.MTpushInterface.mtPush.stopPush()
              
              window.MTpushInterface.mtPush.stopPush()

            
Tampilkan blok kode ini di jendela mengambang

Monitoring Pesan Push

Deskripsi Antarmuka

Disarankan memanggil listener pesan sebelum inisialisasi.

window.MTpushInterface.onMsgReceive(fn)
              
              window.MTpushInterface.onMsgReceive(fn)

            
Tampilkan blok kode ini di jendela mengambang

Deskripsi Parameter

Nama Tipe Deskripsi
fn function Fungsi penerimaan dan pemrosesan pesan

Contoh Pemanggilan

window.MTpushInterface.onMsgReceive(function (res) { if(res.type===0){ // res.data.messages[] // res.data.messages[].msg_id // res.data.messages[].title // res.data.messages[].content // res.data.messages[].extras }else{ // res.data.title } });
              
              window.MTpushInterface.onMsgReceive(function (res) {
   if(res.type===0){
    // res.data.messages[]
    // res.data.messages[].msg_id
    // res.data.messages[].title
    // res.data.messages[].content
    // res.data.messages[].extras
   }else{
    // res.data.title
   }

});

            
Tampilkan blok kode ini di jendela mengambang

Data yang Dikembalikan

Nama Tipe Deskripsi
type number
  • 0: pesan channel Engagelab
  • 1: pesan channel sistem
  • data Object isi pesan

    Array pesan channel Engagelab (messages)

    Nama Tipe Deskripsi
    msg_id string ID pesan
    title string judul pesan
    content string isi pesan
    extras Object Field tambahan pesan

    Data pesan channel sistem

    Mendukung interface w3c NotificationOptions, selengkapnya lihat mdn web docs.

    Cek Status Layanan Push

    window.MTpushInterface.getPushAuthority()
                  
                  window.MTpushInterface.getPushAuthority()
    
                
    Tampilkan blok kode ini di jendela mengambang

    Struktur data yang dikembalikan:

    { mtPush: { code:1, //1 sukses, -1 inisialisasi, 0 gagal msg:'success' }, webPush: { code:1, // 0 webpush tidak tersedia, 1 tersedia, 2 izin dinonaktifkan, 3 izin belum dikonfirmasi msg:'success' } }
                  
                  {
       mtPush: {
         code:1, //1 sukses, -1 inisialisasi, 0 gagal
         msg:'success'
       },
       webPush: {
         code:1, // 0 webpush tidak tersedia, 1 tersedia, 2 izin dinonaktifkan, 3 izin belum dikonfirmasi
         msg:'success'
       }
    }
    
                
    Tampilkan blok kode ini di jendela mengambang
    • Kode error objek WebPush:
    code msg Keterangan
    0 Browser tidak mendukung Notifications API Browser tidak mendukung API notifikasi
    1 Izin notifikasi tersedia, langganan pesan berhasil. Izin notifikasi tersedia, langganan pesan sukses
    2 Izin notifikasi telah dinonaktifkan, langganan pesan gagal. Izin notifikasi dinonaktifkan, langganan pesan gagal
    3 Izin notifikasi belum dikonfirmasi, langganan pesan belum dilakukan. Izin notifikasi belum dikonfirmasi, langganan pesan belum dilakukan
    -1 Browser tidak mendukung Service Worker. Browser tidak mendukung Service Worker
    -2 Service Worker tidak mendukung HTTP. Service Worker tidak mendukung protokol HTTP
    -3 Pendaftaran Service Worker gagal. Registrasi Service Worker gagal
    -4 Izin notifikasi tersedia, tapi langganan pesan gagal. Izin notifikasi tersedia, tapi langganan pesan gagal
    -5 Langganan telah dibatalkan Langganan telah dibatalkan

    Mendapatkan Izin Notifikasi Browser

    window.MTpushInterface.getWebPermission()
                  
                  window.MTpushInterface.getWebPermission()
    
                
    Tampilkan blok kode ini di jendela mengambang

    Deskripsi Return

    • granted : tersedia
    • denied : dinonaktifkan
    • default: izin belum dikonfirmasi

    Pelaporan Pesan Kustom

    Jika pesan kustom perlu dilaporkan untuk statistik, gunakan API pelaporan kustom.

    Laporan tampilan:

    window.MTpushInterface.customDisplayReport('msg_id');//msg_id adalah msg_id dari pesan kustom
                  
                  window.MTpushInterface.customDisplayReport('msg_id');//msg_id adalah msg_id dari pesan kustom
    
                
    Tampilkan blok kode ini di jendela mengambang

    Laporan klik:

    window.MTpushInterface.customClickReport('msg_id');//msg_id adalah msg_id dari pesan kustom
                  
                  window.MTpushInterface.customClickReport('msg_id');//msg_id adalah msg_id dari pesan kustom
    
                
    Tampilkan blok kode ini di jendela mengambang

    Monitoring Disconnect

    Deskripsi Antarmuka

    Jika terjadi disconnect setelah inisialisasi sukses, SDK akan otomatis mencoba reconnect dan sign. Disarankan memanggil event listener ini sebelum inisialisasi, dan lakukan inisialisasi ulang setelah menerima event ini.

    window.MTpushInterface.mtPush.onDisconnect(fn)
                  
                  window.MTpushInterface.mtPush.onDisconnect(fn)
    
                
    Tampilkan blok kode ini di jendela mengambang

    Contoh Pemanggilan

    window.MTpushInterface.mtPush.onDisconnect(function () { });
                  
                  window.MTpushInterface.mtPush.onDisconnect(function () {
    });
    
                
    Tampilkan blok kode ini di jendela mengambang

    Batalkan Langganan Browser

    Berhenti berlangganan notifikasi. Gunakan metode ini saat logout akun atau jika privasi akun tinggi.

    MTpushInterface.unSubscribe();
                  
                  MTpushInterface.unSubscribe();
    
                
    Tampilkan blok kode ini di jendela mengambang

    Set TagsAlias

    window.MTpushInterface.setTagsAlias({})

    MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
                  
                  MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
    
                
    Tampilkan blok kode ini di jendela mengambang

    Deskripsi Parameter

    Nama Tipe Deskripsi
    tags string[] Wajib, panjang array maksimal 1000, tiap elemen maksimal 40 karakter
    alias string wajib, maksimal 40 karakter

    Deskripsi Antarmuka

    Pengembang dapat mengatur tag dan alias melalui antarmuka ini. Perhatikan bahwa antarmuka ini menggunakan logika penimpaan — mengatur ke string kosong akan menghapus tag dan alias yang ada.

    Atur Bahasa Notifikasi

    MTpushInterface.setLan(lan)

    MTpushInterface.setLan(lan, (err) => { alert(err ? "Gagal mengatur bahasa notifikasi: " + err : "Bahasa notifikasi berhasil diatur"); });
                  
                  MTpushInterface.setLan(lan, (err) => {
      alert(err ? "Gagal mengatur bahasa notifikasi: " + err : "Bahasa notifikasi berhasil diatur");
    });
    
                
    Tampilkan blok kode ini di jendela mengambang

    Deskripsi Parameter

    Nama parameter Tipe parameter Deskripsi parameter
    Parameter 1 string Wajib. Parameter bahasa dalam format kode bahasa ISO 639-1, misalnya "cn" untuk bahasa Mandarin, "en" untuk bahasa Inggris, dan "ja" untuk bahasa Jepang
    Parameter 2 Function Callback opsional. Dipanggil setelah pengaturan selesai. Parameter err berisi informasi error jika ada; tanpa err berarti berhasil

    Deskripsi Antarmuka

    Developer dapat menggunakan API ini untuk mengatur bahasa notifikasi secara manual. Setelah pengaturan berhasil, SDK menyimpan bahasa tersebut. Jika userLang tidak dikirim saat inisialisasi berikutnya, bahasa yang tersimpan secara lokal akan digunakan terlebih dahulu.

    Tampilan Prompt Kategori Berulang

    window.MTpushInterface.promptPushCategories();
                  
                  window.MTpushInterface.promptPushCategories();
    
                
    Tampilkan blok kode ini di jendela mengambang

    Deskripsi Antarmuka

    Setelah pengguna berlangganan notifikasi push, pengembang dapat menampilkan prompt kategori beberapa kali sesuai kebutuhan. Ini harus dipanggil setelah SDK diinisialisasi.

    Callback Tampilan Pesan Push

    Deskripsi Antarmuka

    Disarankan memanggil listener pesan sebelum inisialisasi.

    Contoh Pemanggilan

    window.MTpushInterface.onMsgDisplay((msgData) => {});
                  
                  window.MTpushInterface.onMsgDisplay((msgData) => {});
    
                
    Tampilkan blok kode ini di jendela mengambang

    Deskripsi Parameter

    Parameter callback notifikasi pesan msgData:

    { engagelab_ntf_or_msg: number; engagelab_appkey: string; engagelab_passwd: string; engagelab_uid: number; engagelab_mesg_type: string; engagelab_m_str: string; engagelab_a_str: string; type: number; title: string; content: string; msg_id: string; }
                  
                  {
      engagelab_ntf_or_msg: number;
      engagelab_appkey: string;
      engagelab_passwd: string;
      engagelab_uid: number;
      engagelab_mesg_type: string;
      engagelab_m_str: string;
      engagelab_a_str: string;
      type: number;
      title: string;
      content: string;
      msg_id: string;
    }
    
                
    Tampilkan blok kode ini di jendela mengambang

    Parameter callback pesan in-app msgData:

    { title: string; content: string; msg_id: string; ntf_or_msg: number; type: string; }
                  
                  {
      title: string;
      content: string;
      msg_id: string;
      ntf_or_msg: number;
      type: string;
    }
    
                
    Tampilkan blok kode ini di jendela mengambang

    Catatan:

    1. Dalam mode pengeditan HTML untuk pesan in-app, parameter callback title dan content berupa string kosong.

    2. Pesan yang dikirim melalui channel sistem di browser Safari tidak dapat menerima callback tampilan.

    Callback Klik Pesan Push

    Deskripsi Antarmuka

    Disarankan memanggil listener pesan sebelum inisialisasi.

    Contoh Pemanggilan

    window.MTpushInterface.onMsgClick((msgData) => {});
                  
                  window.MTpushInterface.onMsgClick((msgData) => {});
    
                
    Tampilkan blok kode ini di jendela mengambang

    Deskripsi Parameter

    Parameter callback notifikasi pesan msgData:

    { engagelab_ntf_or_msg: number; engagelab_appkey: string; engagelab_passwd: string; engagelab_uid: number; engagelab_mesg_type: string; engagelab_m_str: string; engagelab_a_str: string; type: number; title: string; content: string; msg_id: string; target_event: string | null; position: string; // Posisi klik, 'msgBody' | ID tombol }
                  
                  {
      engagelab_ntf_or_msg: number;
      engagelab_appkey: string;
      engagelab_passwd: string;
      engagelab_uid: number;
      engagelab_mesg_type: string;
      engagelab_m_str: string;
      engagelab_a_str: string;
      type: number;
      title: string;
      content: string;
      msg_id: string;
      target_event: string | null;
      position: string; // Posisi klik, 'msgBody' | ID tombol
    }
    
                
    Tampilkan blok kode ini di jendela mengambang

    Parameter callback pesan in-app msgData:

    { position: 'msgBody' | 'mainBtn' | 'subBtn' | 'closeBtn'; msg_id: number; title: string; content: string; extras: object | null; ntf_or_msg: number; strategy: object | null; target_event: unknown[]; type: number; icon: string; }
                  
                  {
      position: 'msgBody' | 'mainBtn' | 'subBtn' | 'closeBtn';
      msg_id: number;
      title: string;
      content: string;
      extras: object | null;
      ntf_or_msg: number;
      strategy: object | null;
      target_event: unknown[];
      type: number;
      icon: string;
    }
    
                
    Tampilkan blok kode ini di jendela mengambang

    Catatan:

    1. Dalam mode pengeditan HTML untuk pesan in-app, nilai position ditentukan oleh pengembang, dan parameter callback title serta content berupa string kosong.
    2. Pesan yang dikirim melalui channel sistem di browser Safari tidak dapat menerima callback klik.

    kode error

    code message Keterangan
    0 success pemanggilan berhasil
    1000 unknown error error tidak diketahui
    1001 initing , please try again later sedang inisialisasi, silakan coba lagi nanti
    1002 invalid config Konfigurasi awal error
    1003 init failed Inisialisasi gagal, silakan cek detail di konsol
    1004 init timeout inisialisasi timeout
    1005 network error error jaringan, tidak ada jaringan atau tidak dapat terhubung ke websocket
    1006 failed to get baseUrl and reportUrl Permintaan API get-webaddr gagal, cek field content pada callback untuk detailnya
    1007 authentication failed Autentikasi gagal, cek field content pada callback untuk detailnya
    1008 region restricted Terbatas menurut wilayah
    Icon Solid Transparent White Qiyu
    Hubungi Sales