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 {
appkey: string; // Appkey der auf der URORA-Plattform registrierten Anwendung (erforderlich)
user_str: string; // Eindeutige Kennung für den Nutzer (erforderlich)
swUrl?: string; // Standard: "/sw.min." + sdkEnv.version + ".js"
debugMode?: boolean; // Standard: false
webSocketUrl?: string; // Falls nicht angegeben, wird baseUrl verwendet
fail?: (data: dataType | undefined) => void; // Callback im Fehlerfall
success?: (data: dataType | undefined) => void; // Callback bei Erfolg
webPushcallback?: def;
canGetInfo?: (d: MTInitInfo) => void;
custom?: (Callback: () => void) => void; // Callback bei benutzerdefinierter Abfrage, Callback nach Operation aufrufen
maCompletion?: (code: number, msg: string) => void; // Callback nach Abschluss der ma-sdk-Initialisierung
/**
* Weiterleitungslink beim Klick auf eine Benachrichtigung, Priorität: beim Senden gesetzte URL -> InitType.openUrl -> Domain der integrierten Seite
* Für Safari: Vom System ausgelieferte Nachrichten erfordern eine zusätzliche Behandlung: Vor dem Laden des SDKs window.MTpushInterfaceTempData = { openUrl: 'https://example.com' } setzen
*/
openUrl?: string;
/**
* Ob swUrl codiert werden soll
* Anwendungsfall:
* Enthält swUrl Sonderzeichen wie @ und der Server beschränkt den Zugriff auf diese Ressource, kann die Registrierung des Service Workers fehlschlagen;
* Ein Mechanismus zur erneuten Registrierung ist erforderlich; dabei sollte swUrl bei Wiederholungen codiert werden.
*/
encodeSwUrl?: boolean;
}
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](/zh_CN/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
MTpushInterface.init({
appkey: "xxx",
user_str: "adminDemo",
fail(data) {
console.log("Online-Push konnte nicht erstellt werden", data);
},
success(data) {
console.log("Online-Push erfolgreich erstellt", data);
},
webPushcallback(code, tip) {
console.log("Statuscode und Hinweis für Nutzer", code, tip);
},
//swUrl?: string; // Standard "/sw.min." + sdkEnv.version + ".js"
canGetInfo(d) {
// RegId oder alle Daten in d abrufen
console.log("RegId abrufen", MTpushInterface.getRegistrationID(), d);
// MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "swefgwwefwfwfwf" });
},
custom: (reqPermission) => {
// Bei benutzerdefinierter Abfrage muss reqPermission zur Rechteanfrage aufgerufen werden.
document.getElementById("xx")?.addEventListener("click", reqPermission); },
});
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
Benutzerdefinierte Nachrichtendaten melden
Für Statistikzwecke zu benutzerdefinierten Nachrichten kann diese Schnittstelle genutzt werden.
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 unter einem bestimmten Alias setzen oder löschen. Die Logik ist überlagernd. Wird die Benachrichtigung auf einen leeren String gesetzt, können bestehende Tags gelöscht werden.
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:
{
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: Engagelab-Kanalnachricht 1: Systemnachricht
}
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:
{
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; // Klickposition, 'msgBody' | Button-ID
type: string; // 0: Engagelab-Kanalnachricht 1: Systemnachricht
}
Callback-Parameter für In-App-Nachrichten:
{
title: string;
content: string;
msg_id: string;
ntf_or_msg: number;
position: 'msgBody' | 'mainBtn' | 'subBtn' | 'closeBtn';
type: 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 |

