Web SDK Chrome Extension Version Integrationsleitfaden (für V3)

Hinweis: Dieser Leitfaden beschreibt die Standardintegration des MTpush Web SDK für Chrome Extensions auf Basis von Manifest V3. Die Anleitung gilt ausschließlich für Browser-Versionen, die die V3-Extension-Architektur unterstützen.

1. Produkteinführung

Das MTpush Web SDK – Chrome Extension Version ist ein Push-Integrations-Tool für Entwickler, das auf der Chrome-Extension-Architektur (Manifest V3) basiert. Es nutzt systemeigene Benachrichtigungsfunktionen des Chrome-Browsers und eine persistente Verbindung über den Service Worker, um stabile und effiziente Push-Benachrichtigungen für Erweiterungen bereitzustellen.

Dieses SDK unterstützt ausschließlich Chrome-Browser und Chromium-basierte Browser (wie Edge Chromium) und setzt die jeweilige Erweiterungs-Laufzeitumgebung voraus. Es ist keine zusätzliche Autorisierung der Nutzer erforderlich; nach der Initialisierung kann die Erweiterung Push-Nachrichten empfangen.

📦 Hauptfunktionen

• Push-Nachrichten direkt über das Benachrichtigungscenter des Browsers anzeigen
• An die Chrome-Extension-Architektur angepasst, automatische Anmeldung, keine Nutzerwahrnehmung
• Schneller Einstieg durch eine einheitliche API für Initialisierung und Nachrichtenempfang
• Gezielte Ansprache von Nutzergruppen über Tags, Aliase etc.

📌 Anwendungsfälle

• Versand von Erinnerungen, Marketinginformationen, Updates und weiteren Benachrichtigungen an Extension-Nutzer
• Echtzeitübermittlung relevanter Informationen wie Logistikstatus oder Aktionsnachrichten an Nutzer
• Entwicklung von Browser-Utility-Erweiterungen mit Messaging-Funktionen

2. Inhalt des SDK-Archivs

              
              webPushSdk.min.x.x.x-release.zip
├── chrome-extension
│   ├── webSdkExtension.min.x.x.x.js     // Haupt-SDK-Datei
│   ├── swExtension.min.x.x.x.js         // Service-Worker-Datei
│   └── push-demo                        // Beispielprojekt für Chrome-Extensions

            

3. Integrationsprozess

1. Neue Anwendung anlegen

Legen Sie in der EngageLab-Konsole eine neue Anwendung an. Nach erfolgreicher Erstellung wird ein eindeutiger AppKey generiert.
Weitere Informationen finden Sie im Dokument zu Anwendungseinstellungen.

2. Extension-ID hinzufügen

• Ermitteln Sie die Extension-ID Ihrer Chrome-Extension.
• Melden Sie sich in der EngageLab WebPush-Konsole an, gehen Sie zu [Integrationseinstellungen] > [Chrome-Extension-Integration] und geben Sie Name und Extension-ID ein.

Schaubild:

3. SDK-Integration

Schritt 1: SDK herunterladen und Extension konfigurieren

Tragen Sie die folgende Konfiguration in die manifest.json ein:

              
              {
  "manifest_version": 3,
  "permissions": [
    "storage",
    "notifications",
    "tabs",
    "activeTab"
  ],
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["webSdkExtension.min.x.x.x.js"],
      "run_at": "document_end"
    },
    {
      "matches": ["<all_urls>"],
      "js": ["init-sdk.js"],
      "run_at": "document_end"
    }
  ],
  "background": {
    "service_worker": "swExtension.min.x.x.x.js"
  }
}

            

Nach dem Einbinden von webSdkExtension.min.x.x.x.js können Sie die SDK-Methoden über window.MTpushInterfaceExtension aufrufen.

Schritt 2: user_str generieren

Es wird empfohlen, einen Browser-Fingerabdruck zur Generierung einer eindeutigen user_str zu verwenden, um ungültige Nutzerregistrierungen zu vermeiden:

              
              // Ausgelassen: Canvas-, WebGL- und Extension-Fingerprinting-Code (unverändert übernommen)
const visitorId = getFingerprint();
console.log('user_str', visitorId);

            

Schritt 3: SDK initialisieren

              
              if (window.MTpushInterfaceExtension) {
  window.MTpushInterfaceExtension.initSdk({
    appkey: '',      // Von der Konsole generierter AppKey
    user_str: '',    // Browser-Fingerabdruck oder eindeutige Kennung des angemeldeten Nutzers
  });
}

chrome.runtime.onMessage.addListener((message) => {
  switch (message.type) {
    case 'MTPUSH_INIT_SDK_SUCCESS':
      console.log('SDK-Initialisierung erfolgreich:', message.data);
      break;
    case 'MTPUSH_INIT_SDK_FAIL':
      console.log('SDK-Initialisierung fehlgeschlagen:', message.data);
      break;
    case 'MTPUSH_ON_MSG_RECEIVE':
      console.log('Push-Nachricht wurde empfangen:', message.data);
      break;
  }
});

            

MTPUSH_ON_MSG_RECEIVE wird ausgelöst, wenn eine Push-Nachricht empfangen wurde. Dies ist nur auf folgenden Seiten gültig:

1. Seiten, die nach der Installation oder dem Neustart der Extension neu geöffnet wurden;
2. Seiten, die sich aktuell im sichtbaren Vordergrund befinden.

4. Hinweise

1. Die SDK-Initialisierung muss auf einer Seite erfolgen, die nach der Installation der Extension neu geöffnet wurde; alte Seiten können keine Verbindung herstellen.
2. Wird die Extension deaktiviert oder gelöscht, können keine Push-Nachrichten mehr empfangen werden.
3. Nach dem Aktivieren oder Neuladen der Extension muss irgendeine Seite erneut geöffnet werden, um die Initialisierung und Anmeldung durchzuführen.
4. Im selben Browser werden – auch mit identischem AppKey – verschiedene Extensions oder user_str als unterschiedliche Nutzer behandelt.
5. Die Extension benötigt keine Autorisierung der Nutzer für Benachrichtigungsrechte; nach erfolgreicher Initialisierung erfolgt die Anmeldung für Systembenachrichtigungen automatisch.

5. Weitere APIs

Weitere Informationen zur Nutzung der SDK-APIs finden Sie in der offiziellen Dokumentation: Web SDK API

6. Demo-Beispiel ausführen

Das SDK-Archiv enthält ein Beispielprojekt push-demo für Chrome-Extensions, das für schnelle Push-Funktionstests genutzt werden kann:

1. Ersetzen Sie das Verzeichnis lib durch das aktuelle SDK.
2. Tragen Sie den korrekten appkey und user_str in init-sdk.js ein.
3. Öffnen Sie chrome://extensions, aktivieren Sie den Entwicklermodus und laden Sie das entpackte Demo hoch.
4. Öffnen Sie eine beliebige Webseite, um die Initialisierungs- und Anmeldeprozedur abzuschließen.
5. Melden Sie sich in der EngageLab-Konsole an und senden Sie Testnachrichten.
6. Klicken Sie auf das Push-Icon unten rechts auf der Webseite, um regid, Push-Verlauf sowie Tags und Aliase anzuzeigen und zu setzen.
7. Bei einer Fehlermeldung wie „Session Timeout“ erfolgt eine automatische Neuanmeldung der Extension.

Jetzt starten:
Mehr erfahren
Demo buchen