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 }
              
              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
}

            
Diesen Codeblock im schwebenden Fenster anzeigen
  • 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.

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)
              
              window.MTpushInterface.init(Object:InitType)

            
Diesen Codeblock im schwebenden Fenster anzeigen

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"); } }); }, });
              
              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");
      }
    });
  },
});

            
Diesen Codeblock im schwebenden Fenster anzeigen

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()
              
              window.MTpushInterface.getRegistrationID()

            
Diesen Codeblock im schwebenden Fenster anzeigen

Anwendungsbeispiel

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

            
Diesen Codeblock im schwebenden Fenster anzeigen

Push beenden

Mit dieser API wird die Push-Verbindung zum Backend getrennt und der Empfang von Push-Nachrichten gestoppt.

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

            
Diesen Codeblock im schwebenden Fenster anzeigen

Push-Nachrichten überwachen (Listener registrieren)

Schnittstellenbeschreibung

Es wird empfohlen, den Nachrichten-Listener bereits vor der Initialisierung zu registrieren.

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

            
Diesen Codeblock im schwebenden Fenster anzeigen

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 } });
              
              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
   }
});

            
Diesen Codeblock im schwebenden Fenster anzeigen

Rückgabedaten

Parametername Typ Beschreibung
type number
  • 0: Engagelab-Kanalnachricht
  • 1: Systemnachricht
  • 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()
                  
                  window.MTpushInterface.getPushAuthority()
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    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' } }
                  
                  {
       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'
       }
    }
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen
    • 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()
                  
                  window.MTpushInterface.getWebPermission()
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    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
                  
                  window.MTpushInterface.customDisplayReport('msg_id');//msg_id ist die ID der benutzerdefinierten Nachricht
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    Klick-Reporting:

    window.MTpushInterface.customClickReport('msg_id');//msg_id ist die ID der benutzerdefinierten Nachricht
                  
                  window.MTpushInterface.customClickReport('msg_id');//msg_id ist die ID der benutzerdefinierten Nachricht
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    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)
                  
                  window.MTpushInterface.mtPush.onDisconnect(fn)
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    Anwendungsbeispiel

    window.MTpushInterface.mtPush.onDisconnect(function () { });
                  
                  window.MTpushInterface.mtPush.onDisconnect(function () {
    });
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    Browser-Abonnement kündigen

    Benachrichtigungsabonnement kündigen. Diese Methode kann z. B. beim Ausloggen oder bei Konten mit hohem Datenschutzbedarf genutzt werden.

    MTpushInterface.unSubscribe();
                  
                  MTpushInterface.unSubscribe();
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    TagsAlias setzen

    window.MTpushInterface.setTagsAlias({})

    MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
                  
                  MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    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"); });
                  
                  MTpushInterface.setLan(lan, (err) => {
      alert(err ? "Benachrichtigungssprache konnte nicht festgelegt werden: " + err : "Benachrichtigungssprache erfolgreich festgelegt");
    });
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    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();
                  
                  window.MTpushInterface.promptPushCategories();
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    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) => {});
                  
                  window.MTpushInterface.onMsgDisplay((msgData) => {});
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    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; }
                  
                  {
      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;
    }
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    Callback-Parameter für In-App-Nachrichten:

    { 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;
    }
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    Hinweis:

    1. Im HTML-Bearbeitungsmodus für In-App-Nachrichten sind die Callback-Parameter title und content leere Strings.
    2. Ü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) => {});
                  
                  window.MTpushInterface.onMsgClick((msgData) => {});
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    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 }
                  
                  {
      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
    }
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    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; }
                  
                  {
      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;
    }
    
                
    Diesen Codeblock im schwebenden Fenster anzeigen

    Hinweis:

    1. Im HTML-Bearbeitungsmodus für In-App-Nachrichten wird der Wert von position von Entwicklern bestimmt, die Callback-Parameter title und content sind leere Strings.
    2. Ü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
    Icon Solid Transparent White Qiyu
    Vertrieb kontaktieren