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
}
- 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.
- openUrl: URL yang dibuka saat notifikasi diklik
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)
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");
}
});
},
});
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()
Contoh Pemanggilan
var rid = window.MTpushInterface.getRegistrationID();
Hentikan Push
Panggil API ini untuk memutus koneksi push ke backend dan menghentikan penerimaan pesan push.
window.MTpushInterface.mtPush.stopPush()
Monitoring Pesan Push
Deskripsi Antarmuka
Disarankan memanggil listener pesan sebelum inisialisasi.
window.MTpushInterface.onMsgReceive(fn)
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
}
});
Data yang Dikembalikan
| Nama | Tipe | Deskripsi |
|---|---|---|
| type | number | |
| 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()
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'
}
}
- 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()
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
Laporan klik:
window.MTpushInterface.customClickReport('msg_id');//msg_id adalah msg_id dari pesan kustom
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)
Contoh Pemanggilan
window.MTpushInterface.mtPush.onDisconnect(function () {
});
Batalkan Langganan Browser
Berhenti berlangganan notifikasi. Gunakan metode ini saat logout akun atau jika privasi akun tinggi.
MTpushInterface.unSubscribe();
Set TagsAlias
window.MTpushInterface.setTagsAlias({})
MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
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");
});
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();
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) => {});
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;
}
Parameter callback pesan in-app msgData:
{
title: string;
content: string;
msg_id: string;
ntf_or_msg: number;
type: string;
}
Catatan:
Dalam mode pengeditan HTML untuk pesan in-app, parameter callback
titledancontentberupa string kosong.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) => {});
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
}
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;
}
Catatan:
- Dalam mode pengeditan HTML untuk pesan in-app, nilai
positionditentukan oleh pengembang, dan parameter callbacktitlesertacontentberupa string kosong.- 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 |










