Web SDK-Integrationsleitfaden

Dieses Dokument ist der Standard-Integrationsleitfaden für das MA Web SDK.

Produktbeschreibung

Das MA Web SDK bietet Funktionen zur Datenerfassung und -berichterstattung für Szenarien wie EUID-Generierung, Setzen von Benutzereigenschaften und Ereignisberichterstattung.

Integrationsoptionen

Das MA Web SDK unterstützt 2 Integrationsarten: gemeinsam mit WebPush oder nur das MA Web SDK allein.

• Gemeinsam mit WebPush: Aktivieren Sie beim Integrieren des EngageLab WebPush-Moduls die MA-Funktion; das MA SDK wird dann automatisch geladen.
• Nur MA Web SDK: Binden Sie die MA SDK-Adresse direkt in Ihre Website ein, ohne WebPush-Funktionen.

Gemeinsam mit WebPush

Vorbereitungen vor der Integration

• Sie müssen zusätzlich das WebPush-Modul integrieren.
• Stellen Sie eine erreichbare HTTPS-Webdienst-Domain bereit. Nach der Integration müssen die Seiten unter dieser Domain getestet und debuggt werden. Web-Offline-Push unterstützt kein lokales Debugging und kein HTTP.
• Öffnen Sie EngageLab WebPush und tragen Sie auf der Seite [Integrationseinstellungen] – [Website-Domainname] die HTTPS-Webdienst-Domain ein.

Anwendungsinformationen erhalten

Sie müssen eine Anwendung in der WebPush-Konsole erstellen. Nach erfolgreicher Erstellung wird automatisch ein AppKey generiert, der die Anwendung identifiziert. Weitere Informationen finden Sie im Dokument zu den Anwendungseinstellungen.

MA-Datenquelle konfigurieren

Gehen Sie im MA-Projekt zu Datenquellen – Datenquelle hinzufügen – Web, wählen Sie „Gemeinsam mit WebPush verwenden", wählen Sie in der Dropdown-Liste die in WebPush erstellte Anwendung aus und speichern Sie.

SDK-Zugriff

Gehen Sie zur Konsole, laden Sie das SDK herunter und binden Sie das JavaScript auf jeder Seite ein:

              
              <script type="text/javascript" src="./WebSDK.3.3.4.js"></script>

            

Hinweise

Nachdem Sie dieses JavaScript eingebunden haben, übergeben Sie die Eigenschaft maOpen mit dem Wert true, um die MA-Konfiguration zu aktivieren. Danach können Sie die MA-APIs und -Funktionen nutzen.

SDK-Initialisierung

              
                  //  Initialisierung (MA aktivieren)
  MTpushInterface.init({
    appkey: "", // Erforderlich, siehe oben „Anwendungsinformationen erhalten"
    user_str: "adminDemo", // Erforderlich, Benutzerkennung zur Identifizierung des Benutzers
    swUrl: "url", // Standard: "/sw.min." + sdkEnv.version + ".js". Diese Konfiguration gibt die Adresse der Service-Worker-Datei an. Die Domain muss die aktuelle Domain sein, und der Pfad bestimmt den Geltungsbereich des Service Workers.
    debugMode: true,// Legt fest, ob der Debug-Modus aktiviert wird. true gibt mehr Log-Informationen aus; false gibt nur Logs der Stufen w und e aus.
    channel: "default-channel",// Kanalname, Standard: default-channel
    appName: "string",// Legt den Website-Namen für die Berichterstattung fest
    maOpen: true, // Schalter zur Aktivierung der MA-Funktionen
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123" },// Legt die Benutzerkennung während der MA-Initialisierung fest. Unterstützt ab Version 3.3.4; geeignet für Unternehmen, die MA-Dienste ausschließlich für eingeloggte Mitglieder bereitstellen
    maDataCollectionEnabled: false, // Anfangsstatus der MA-Datenerfassung; ohne Angabe standardmäßig aktiviert. Unterstützt ab WebPush SDK 3.3.9
    maCompletion: (code, msg) => {// Callback der MA-Initialisierung
                if (code === 0) {
                    console.log("✅MA SDK erfolgreich initialisiert!");
                } else {
                    console.error("❌MA SDK-Initialisierung fehlgeschlagen:", msg);
                }
    }
  });

            

Datenerfassungsschalter (gemeinsam mit WebPush)

Unterstützt ab: MA Web SDK 2.2.0, WebPush SDK 3.3.9

• Übergeben Sie bei der Initialisierung mit MTpushInterface.init den Wert von maDataCollectionEnabled dynamisch entsprechend dem Einwilligungsstatus des Benutzers; das WebPush SDK reicht ihn an das MA SDK durch. Codieren Sie die Konfiguration nicht fest, da sonst bei jeder Initialisierung der Status auf den fest codierten Wert zurückgesetzt wird.
• Wenn sich der Datenerfassungsstatus des Benutzers ändert, rufen Sie window.MAInterface.setDataCollectionEnabled(true/false) auf, nachdem der maCompletion-Callback ausgelöst wurde. maCompletion ist das Signal, dass das MA SDK verfügbar ist; davor ist window.MAInterface möglicherweise noch nicht geladen.
• Während der Deaktivierung können WebPush-Benachrichtigungen weiterhin zugestellt und angeklickt werden, die Konversionsattribution der Push-Klicks wird jedoch nicht mehr erfasst.

Ausführliche Informationen finden Sie unter Datenerfassungsschalter.

Nur MA Web SDK

MA-Datenquelle konfigurieren

Gehen Sie im MA-Projekt zu Datenquellen – Datenquelle hinzufügen – Web, wählen Sie unter „Gemeinsam mit WebPush verwenden?" die Option „Nicht verwenden", geben Sie den Namen der Datenquelle und die Website-Domain ein. Nach dem Speichern erhalten Sie den AppKey der Web-Datenquelle.

• Stellen Sie eine erreichbare HTTPS-Webdienst-Domain bereit. Nach der Integration müssen die Seiten unter dieser Domain getestet und debuggt werden.

SDK-Zugriff

Binden Sie auf jeder Seite das folgende JavaScript ein:

              
              <script type="text/javascript" src="https://websdk-res.engagelab.com/lib/ma-web.min.js"></script>
        

            

Nach dem Einbinden dieses JavaScripts können Sie das globale Objekt MAInterface auf Window verwenden.

Besonderer Hinweis: Verwenden Sie diesen Link direkt und laden Sie diese Datei nicht in Ihr Projekt herunter. Andernfalls kann die Statistik ausfallen, nachdem wir Datenstrukturen oder API-Schnittstellen aktualisiert haben.

SDK-Initialisierung

              
                window.MAInterface.init({
    appKey: "7ccf93e0950b5e22f4ca2124",  // Erforderlich, siehe oben „Anwendungsinformationen erhalten"
    debugMode: true,
    channel: "default-channel22",// Kanalname, Standard: default-channel
    appName: "EngageLab-MA test-appName", // Website-Name, wird als app_name in den Geräteeigenschaften und bei der Ereignisberichterstattung gesetzt
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123", email: "user@example.com", phone: "+8613800000000" }, // Legt die Benutzerkennung während der MA-Initialisierung fest; unterstützt user_id, anonymous_id, email und phone
      completion: (code, msg) => {
        if (code === 0) {
            console.log("✅ SDK erfolgreich initialisiert!");
        } else {
            console.error("❌ SDK-Initialisierung fehlgeschlagen:", msg);
        }
    }
  })
        

            

Hinweise zur Benutzerkennung

• userIdentity unterstützt 4 Arten von Benutzerkennungen: user_id, anonymous_id, email und phone (email und phone werden ab Version 2.1.0 unterstützt). Geben Sie mindestens eine an. Die Regeln der einzelnen Felder finden Sie unter Benutzerkennung festlegen.
• Felder, die bei der Initialisierung nicht den Regeln entsprechen, werden ignoriert, und in der Konsole wird eine Warnung ausgegeben; die übrigen gültigen Felder bleiben wirksam.
• email und phone dienen dem Abgleich der Benutzeridentität und sind keine Kontaktinformationen. Die für die Kontaktaufnahme verwendete E-Mail-Adresse und Telefonnummer legen Sie über die Schnittstelle „Benutzerkontaktinformationen festlegen" (setUserContact) fest.

Erneute Initialisierung und Wechsel des AppKey

Unterstützt ab: 2.1.0

Nach der Initialisierung des SDK können Sie init erneut aufrufen, ohne die Seite neu zu laden:

• Gleicher AppKey: Das SDK ruft die EUID erneut ab. Wird gleichzeitig eine neue userIdentity übergeben, ruft das SDK die EUID mit der neuen Benutzerkennung erneut ab. Dies eignet sich für den Kontowechsel nach dem Abmelden innerhalb derselben Seite.
• Anderer AppKey: Das SDK wechselt zur MA-Datenquelle des neuen AppKey; nachfolgende Daten werden an die neue Datenquelle gemeldet. Vor dem Wechsel erzeugte Daten werden weiterhin an die ursprüngliche Datenquelle gemeldet.
• Mehrere init-Aufrufe werden in der Aufrufreihenfolge nacheinander ausgeführt; jeder Aufruf liefert sein Ergebnis über completion zurück. Maßgeblich ist jeweils das Ergebnis des zugehörigen Callbacks.
• Der Wechsel des AppKey wird nur bei alleiniger Verwendung des MA Web SDK unterstützt; die Integrationsart „gemeinsam mit WebPush" unterstützt ihn nicht.

              
                // Zu einer anderen MA-Datenquelle wechseln
  window.MAInterface.init({
    appKey: "AppKey einer anderen Datenquelle",
    completion: (code, msg) => {
      console.log(code, msg)
    }
  })

            

Kanal-Kontakt-ID festlegen

Unterstützt ab: 2.1.0

Um für WebPush oder einen Drittanbieter-Push-Kanal eine RID oder ein Token festzulegen, rufen Sie nach erfolgreicher SDK-Initialisierung Folgendes auf:

              
                window.MAInterface.setChannelValue(136, ["push rid or token"], (code, message) => { })

            

• channelId: Die ID des in der MA-Konsole konfigurierten Push-Kanals; muss größer als 0 sein.
• values: Array von RIDs oder Tokens; weder das Array noch seine Elemente dürfen leer sein. Ändert sich die RID oder das Token, muss die Schnittstelle erneut aufgerufen werden.

Ausführliche Informationen finden Sie unter Kanal-Kontakt-ID festlegen.

Datenerfassungsschalter

Unterstützt ab: 2.2.0

Die Anwendung steuert anhand der Einwilligung des Benutzers, ob das MA SDK Daten erfasst. Nach der Deaktivierung erzeugt, zwischenspeichert und meldet das SDK keine Ereignisse, Benutzereigenschaften, UTM- und Geräteinformationen; Initialisierung, Benutzerkennung, Kontaktinformationen und Kanal-Kontakt-ID bleiben wie gewohnt verfügbar. Der Status wird lokal im Browser gespeichert und bleibt nach dem Neuladen erhalten.

              
                // Übergeben Sie bei der Initialisierung den Wert von dataCollectionEnabled dynamisch entsprechend dem Einwilligungsstatus des Benutzers. Codieren Sie die Konfiguration nicht fest, da sonst bei jeder Initialisierung der Status auf den fest codierten Wert zurückgesetzt wird
  window.MAInterface.init({
    appKey: "your appKey",
    dataCollectionEnabled: false, // Ohne Angabe standardmäßig aktiviert
    completion: (code, msg) => {}
  })

  // Nachdem der Benutzer die Einwilligung erteilt / widerrufen hat
  window.MAInterface.setDataCollectionEnabled(true, (code, msg) => {})
  window.MAInterface.setDataCollectionEnabled(false, (code, msg) => {})

            

• Entspricht der gesetzte Wert dem aktuellen Status, wird keine Umschaltung ausgelöst; das Synchronisieren der Benutzerauswahl bei jedem Seitenaufruf hat daher keine zusätzlichen Auswirkungen.
• Wird während der Deaktivierung eine Benutzereigenschaften-Schnittstelle aufgerufen, gibt completion -8 zurück; Schnittstellen ohne Callback wie Ereignisse und UTM verwerfen die Daten stillschweigend.
• Bei eingeschränktem Speicher (localStorage nicht verfügbar) gilt der Schalterstatus nur im aktuellen Tab.

Ausführliche Informationen finden Sie unter Datenerfassungsschalter.

Weitere API-Schnittstellen

Die Verwendung weiterer APIs finden Sie in der Schnittstellendokumentation: Web SDK API.