Web SDK API
Authentifizierung
Bei der Initialisierung muss der Entwickler die erforderlichen Informationen übergeben. Diese Datenstruktur wird vom Server des Entwicklers generiert und an den Browser zurückgesendet. Sie dient zur Initialisierung von MTpush und autorisiert den Browser zur Ausführung von MTpush. Entwickler müssen sicherstellen, dass alle Nutzer, die diese Daten abrufen können, legitim sind.
Initialisierungsdatenstruktur
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
}
- Parameter:
- openUrl: Beim Klick auf eine Benachrichtigung geöffnete URL
- Wird keine URL beim Senden angegeben, wird dieser Wert als Weiterleitung verwendet;
- Wenn nicht gesetzt, erfolgt die Weiterleitung standardmäßig zur Integrationsdomain;
- Bei Mehr-Domain-Integration ermöglicht dieser Parameter die Weiterleitung zur jeweiligen URL;
- encodeSwUrl: Ob swUrl codiert werden soll
- Relevant, wenn swUrl Sonderzeichen (z. B. @) enthält und der Server den Zugriff einschränkt, was die Service-Worker-Registrierung verhindern kann; Mechanismus zur erneuten Registrierung ergänzen und swUrl beim erneuten Versuch codieren.
- regidSearchPath: Seitenpfad für die Abfrage der Registration ID; Standard: /engagelab/regid. Siehe Anleitung zur Registration-ID-Abfrage.
- openUrl: Beim Klick auf eine Benachrichtigung geöffnete URL
Innerhalb desselben Scopes kann nur ein Service Worker registriert werden. Tritt beim Initialisieren ein Fehler wie „Failed to execute 'subscribe' on 'PushManager': Subscription failed - no active Service Worker“ auf, prüfen Sie bitte, ob Konflikte mit anderen Service Workern bestehen. Gegebenenfalls müssen die Service Worker zusammengeführt oder der Scope angepasst werden.
SDK-Initialisierung
Schnittstellenbeschreibung
Initialisiert die Schnittstelle.
window.MTpushInterface.init(Object:InitType)
Parameterbeschreibung
- Details siehe [InitType Beschreibung](/de_DE/docs/web-push/sdk/web-sdk-api#Initialize data structure).
- Beschreibung der Callback-Objektdaten:
| Fehlercode | Typ | Beschreibung |
|---|---|---|
| code | number | Rückgabecode, 0 = Erfolg, andere Werte = Fehler, siehe Fehlercodes |
| message | string | Ergebnisbeschreibung |
| content | string | Fehlermeldung bei Registrierungsfehler 1003 |
Anwendungsbeispiel
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");
}
});
},
});
RegistrationID abrufen
Schnittstellenbeschreibung
Mit dieser API können Sie die RegistrationID für das aktuelle Konto abrufen. Der Wert wird nur nach erfolgreicher Initialisierungssignatur zurückgegeben, andernfalls ein leerer String. Diese Methode muss nach dem Auslösen des canGetInfo-Callbacks aufgerufen werden.
window.MTpushInterface.getRegistrationID()
Anwendungsbeispiel
var rid = window.MTpushInterface.getRegistrationID();
Push beenden
Mit dieser API wird die Push-Verbindung zum Backend getrennt und der Empfang von Push-Nachrichten gestoppt.
window.MTpushInterface.mtPush.stopPush()
Push-Nachrichten überwachen (Listener registrieren)
Schnittstellenbeschreibung
Es wird empfohlen, den Nachrichten-Listener bereits vor der Initialisierung zu registrieren.
window.MTpushInterface.onMsgReceive(fn)
Parameterbeschreibung
| Parametername | Typ | Beschreibung |
|---|---|---|
| fn | function | Funktion zur Verarbeitung eingehender Nachrichten |
Anwendungsbeispiel
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
}
});
Rückgabedaten
| Parametername | Typ | Beschreibung |
|---|---|---|
| type | number | |
| data | Object | Nachrichteninhalt |
Engagelab-Kanalnachrichten-Array (messages)
| Parametername | Typ | Beschreibung |
|---|---|---|
| msg_id | string | Nachrichten-ID |
| title | string | Nachrichtentitel |
| content | string | Nachrichteninhalt |
| extras | Object | Zusätzliche Felder |
Systemnachrichten-Daten
Unterstützt das w3c-Interface NotificationOptions, Details siehe mdn web docs.
Push-Service-Status prüfen
window.MTpushInterface.getPushAuthority()
Die Rückgabedatenstruktur ist wie folgt:
{
mtPush: {
code:1, // 1 = erfolgreich, -1 = Initialisierung, 0 = fehlgeschlagen
msg:'success'
},
webPush: {
code:1, // 0 = nicht verfügbar (Browser unterstützt nicht) 1 = verfügbar 2 = Berechtigung deaktiviert 3 = Berechtigung nicht bestätigt
msg:'success'
}
}
- Fehlercodes des WebPush-Objekts:
| Fehlercode | msg | Bemerkung |
|---|---|---|
| 0 | Der Browser unterstützt die Notifications API nicht | Browser unterstützt keine Benachrichtigungen |
| 1 | Benachrichtigungsberechtigungen verfügbar, Nachricht abonniert | Berechtigung verfügbar, Abo erfolgreich |
| 2 | Benachrichtigungsberechtigungen deaktiviert, Abo fehlgeschlagen | Berechtigung deaktiviert, Abo fehlgeschlagen |
| 3 | Benachrichtigungsberechtigungen nicht bestätigt, kein Abo | Berechtigung nicht bestätigt, kein Abo |
| -1 | Browser unterstützt keinen Service Worker | |
| -2 | Service Worker unterstützt kein HTTP | |
| -3 | Registrierung des Service Workers fehlgeschlagen | |
| -4 | Berechtigung verfügbar, Abo fehlgeschlagen | |
| -5 | Abo wurde storniert |
Browser-Benachrichtigungsberechtigung abfragen
window.MTpushInterface.getWebPermission()
Rückgabeparameter
- granted : verfügbar
- denied : deaktiviert
- default: Berechtigung nicht bestätigt
Reporting für benutzerdefinierte Nachrichten
Für Statistikzwecke zu benutzerdefinierten Nachrichten können die benutzerdefinierten Reporting-APIs genutzt werden.
Anzeige-Reporting:
window.MTpushInterface.customDisplayReport('msg_id');//msg_id ist die ID der benutzerdefinierten Nachricht
Klick-Reporting:
window.MTpushInterface.customClickReport('msg_id');//msg_id ist die ID der benutzerdefinierten Nachricht
Verbindungsüberwachung trennen
Schnittstellenbeschreibung
Kommt es nach erfolgreicher Initialisierung zu einer Trennung, versucht das SDK automatisch, sich erneut zu verbinden und zu signieren. Es wird empfohlen, diesen Listener bereits vor der Initialisierung zu registrieren und nach Empfang dieses Events die Initialisierung erneut aufzurufen.
window.MTpushInterface.mtPush.onDisconnect(fn)
Anwendungsbeispiel
window.MTpushInterface.mtPush.onDisconnect(function () {
});
Browser-Abonnement kündigen
Benachrichtigungsabonnement kündigen. Diese Methode kann z. B. beim Ausloggen oder bei Konten mit hohem Datenschutzbedarf genutzt werden.
MTpushInterface.unSubscribe();
TagsAlias setzen
window.MTpushInterface.setTagsAlias({})
MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
Parameterbeschreibung
| Parametername | Typ | Beschreibung |
|---|---|---|
| tags | string[] | Pflichtfeld, max. 1.000 Elemente, je max. 40 Zeichen |
| alias | string | Pflichtfeld, max. 40 Zeichen |
Schnittstellenbeschreibung
Über diese Schnittstelle können Entwickler Tags und Alias setzen. Beachten Sie, dass diese Schnittstelle eine Überschreibungslogik verwendet — wird ein leerer String gesetzt, werden die vorhandenen Tags und der Alias gelöscht.
Benachrichtigungssprache festlegen
MTpushInterface.setLan(lan)
MTpushInterface.setLan(lan, (err) => {
alert(err ? "Benachrichtigungssprache konnte nicht festgelegt werden: " + err : "Benachrichtigungssprache erfolgreich festgelegt");
});
Parameterbeschreibung
| Parametername | Typ | Beschreibung |
|---|---|---|
| Parameter 1 | string | Pflichtfeld. Sprachparameter im ISO-639-1-Format, z. B. "cn" für Chinesisch, "en" für Englisch und "ja" für Japanisch |
| Parameter 2 | Function | Optionaler Callback. Wird nach Abschluss der Einstellung aufgerufen. err enthält Fehlerinformationen, falls vorhanden; ohne err war der Aufruf erfolgreich |
Schnittstellenbeschreibung
Entwickler können mit dieser API die Benachrichtigungssprache manuell festlegen. Nach erfolgreicher Einstellung speichert das SDK die Sprache. Wenn bei der nächsten Initialisierung kein userLang übergeben wird, verwendet das SDK zuerst die lokal gespeicherte Sprache.
Mehrfache Anzeige von Kategorien-Prompts
window.MTpushInterface.promptPushCategories();
Schnittstellenbeschreibung
Nach dem Abonnieren von Push-Benachrichtigungen können Entwickler beliebig oft Kategorien-Prompts anzeigen. Dies muss nach der SDK-Initialisierung aufgerufen werden.
Callback für Push-Nachrichtenanzeige
Schnittstellenbeschreibung
Es wird empfohlen, den Listener bereits vor der Initialisierung zu registrieren.
Anwendungsbeispiel
window.MTpushInterface.onMsgDisplay((msgData) => {});
Parameterbeschreibung
Callback-Parameter für Benachrichtigungsnachrichten 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;
}
Callback-Parameter für In-App-Nachrichten:
{
title: string;
content: string;
msg_id: string;
ntf_or_msg: number;
type: string;
}
Hinweis:
- Im HTML-Bearbeitungsmodus für In-App-Nachrichten sind die Callback-Parameter
titleundcontentleere Strings.- Über den Systemkanal im Safari-Browser ausgelieferte Nachrichten erhalten keinen Anzeige-Callback.
Callback für Klick auf Push-Nachricht
Schnittstellenbeschreibung
Es wird empfohlen, den Listener bereits vor der Initialisierung zu registrieren.
Anwendungsbeispiel
window.MTpushInterface.onMsgClick((msgData) => {});
Parameterbeschreibung
Callback-Parameter für Benachrichtigungsnachrichten 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; // Klickposition, 'msgBody' | Button-ID
}
Callback-Parameter für In-App-Nachrichten:
{
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;
}
Hinweis:
- Im HTML-Bearbeitungsmodus für In-App-Nachrichten wird der Wert von
positionvon Entwicklern bestimmt, die Callback-Parametertitleundcontentsind leere Strings.- Über den Systemkanal im Safari-Browser ausgelieferte Nachrichten erhalten keinen Klick-Callback.
Fehlercodes
| Fehlercode | message | Bemerkung |
|---|---|---|
| 0 | success | Aufruf erfolgreich |
| 1000 | unknown error | Unbekannter Fehler |
| 1001 | initing , please try again later | Initialisierung läuft, bitte später erneut versuchen |
| 1002 | invalid config | Fehlerhafte Initialkonfiguration |
| 1003 | init failed | Initialisierung fehlgeschlagen, Details siehe Konsole |
| 1004 | init timeout | Initialisierungstimeout |
| 1005 | network error | Netzwerkfehler, keine Verbindung oder keine Websocket-Verbindung |
| 1006 | failed to get baseUrl and reportUrl | get-webaddr-API-Anfrage fehlgeschlagen, Details siehe content-Feld im Callback |
| 1007 | authentication failed | Authentifizierung fehlgeschlagen, Details siehe content-Feld im Callback |
| 1008 | region restricted | Region eingeschränkt |










