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 {
appkey: string; // Appkey aplikasi yang didaftarkan di platform URORA, wajib
user_str: string; // Identitas unik pengguna, wajib
swUrl?: string; // Default "/sw.min." + sdkEnv.version + ".js"
debugMode?: boolean; // Default false
webSocketUrl?: string; // Jika kosong, gunakan baseUrl
fail?: (data: dataType | undefined) => void; // Callback saat inisialisasi gagal
success?: (data: dataType | undefined) => void; // Callback saat inisialisasi berhasil
webPushcallback?: def;
canGetInfo?: (d: MTInitInfo) => void;
custom?: (Callback: () => void) => void; // Callback prompt kustom, panggil Callback setelah selesai
maCompletion?: (code: number, msg: string) => void; // Callback selesai inisialisasi ma-sdk
/**
* Tautan redirect saat klik notifikasi, prioritas: URL saat kirim notifikasi -> InitType.openUrl -> domain halaman integrasi
* Untuk Safari, pesan via channel sistem perlu penanganan tambahan: set window.MTpushInterfaceTempData = { openUrl: 'https://example.com' } sebelum memuat SDK
*/
openUrl?: string;
/**
* Apakah swUrl perlu di-encode
* Skenario:
* Jika swUrl mengandung karakter khusus seperti @ dan server membatasi akses resource URL ini, bisa menyebabkan pendaftaran Service Worker gagal;
* Dibutuhkan mekanisme retry, swUrl harus di-encode saat retry.
*/
encodeSwUrl?: boolean;
}
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](/zh_CN/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
MTpushInterface.init({
appkey: "xxx",
user_str: "adminDemo",
fail(data) {
console.log("Gagal membuat push online", data);
},
success(data) {
console.log("Push online berhasil dibuat", data);
},
webPushcallback(cod, tip) {
console.log("Kode status dan pesan yang didapatkan user", code, tip);
},
//swUrl?: string; //default "/sw.min." + sdkEnv.version + ".js"
canGetInfo(d) {
//Pada saat ini, Anda bisa mendapatkan RegId atau seluruh data dalam d
console.log("Dapatkan RegId", MTpushInterface.getRegistrationID(), d);
// MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "swefgwwefwfwfwf" });
},
custom: (reqPermission) => {
//Jika menggunakan prompt kustom, wajib panggil reqPermission untuk meminta izin. Dapatkan fungsi permintaan izin pada callback custom dan panggil langsung reqPermission pada waktu yang tepat.
document.getElementById("xx")?.addEventListener("click", reqPermission); },
});
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
Laporan Data Pesan Kustom
Jika perlu statistik data pesan kustom, gunakan interface pelaporan kustom untuk melaporkan data.
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 dan menghapus tag di bawah alias tertentu melalui antarmuka ini. Antarmuka ini bersifat overlay logic. Jika tag diatur ke string kosong, tag yang ada akan dihapus.
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:
{
title: string;
content: string;
msg_id: string;
ntf_or_msg: number;
engagelab_appkey: string;
engagelab_passwd: string;
engagelab_uid: string;
engagelab_url: string;
type: string; // 0: pesan channel Engagelab 1: pesan channel sistem
}
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:
{
title: string;
content: string;
msg_id: string;
ntf_or_msg: number;
engagelab_appkey: string;
engagelab_passwd: string;
engagelab_uid: string;
engagelab_url: string;
position: string; // Posisi klik, 'msgBody' | ID tombol
type: string; // 0: pesan channel Engagelab 1: pesan channel sistem
}
Parameter callback pesan in-app msgData:
{
title: string;
content: string;
msg_id: string;
ntf_or_msg: number;
position: 'msgBody' | 'mainBtn' | 'subBtn' | 'closeBtn';
type: 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 |










