API-Leitfaden

Benutzerkennung festlegen

Unterstützte Versionen

Die Kennungen email und phone werden unterstützt ab: 2.1.0

Schnittstellen-Definition

• identifyAccount(user);
  • Schnittstellen-Beschreibung:
    • Legt die Benutzerkennung fest, z. B. eine Mitgliedskartennummer.
  • Parameterbeschreibung
    • identity: Die Benutzerkennungs-ID. Als Key werden die 4 Werte user_id, anonymous_id, email und phone unterstützt; mindestens einer muss angegeben werden, nicht alle sind erforderlich
    • completion: Die Callback-Funktion
  • Regeln für Benutzerkennungen
    • user_id: Nach dem Entfernen führender und nachfolgender Leerzeichen nicht leer, höchstens 255 Zeichen, darf nicht 0, null, undefined oder nan sein (ohne Berücksichtigung der Groß-/Kleinschreibung)
    • anonymous_id: Nach dem Entfernen führender und nachfolgender Leerzeichen nicht leer, höchstens 256 Zeichen
    • email: Die E-Mail-Adresse des Benutzers; nach dem Entfernen führender und nachfolgender Leerzeichen nicht leer, höchstens 256 Zeichen, muss ein gültiges E-Mail-Format haben, z. B. user@example.com
    • phone: Die Telefonnummer des Benutzers; muss im E.164-Format mit Länder- oder Regionscode vorliegen, z. B. +8613800000000
    • Verstößt ein Feld gegen die Regeln, wird bei diesem Aufruf keine Anfrage gesendet; completion gibt -1 zurück und message enthält den konkreten Grund

Beispielaufruf

              
                  let user = {completion: (code, message)=>{}, identity:{"user_id":"value","anonymous_id":"value","email":"user@example.com","phone":"+8613800000000"}}
    window.MAInterface.identifyAccount(user)

            

email und phone dienen hier dem Abgleich der Benutzeridentität und können eine neue EUID zurückliefern. Sie sind nicht austauschbar mit den Kontaktinformationen, die über „Benutzerkontaktinformationen festlegen" (setUserContact) gesetzt werden.

EUID abrufen

Schnittstellen-Definition

• + EUID()
  • Schnittstellen-Beschreibung:
    • Ruft die EUID von EngageLab MA ab

Beispielaufruf

              
                  window.MAInterface.EUID((code,euid)=>{
        console.log(code, euid)
    })

            

Benutzerkontaktinformationen festlegen

Schnittstellen-Definition

• setUserContact(user)
  • Schnittstellen-Beschreibung:
    • Unterstützt das gleichzeitige Festlegen mehrerer Kontaktarten. Der Key ist der Name der Kontaktart, der Value der Kontaktwert. Aktuell werden die 4 Kontaktarten email, mobile_phone, landline_phone und whatsapp_phone unterstützt
  • Parameterbeschreibung
    • contacts: Die Kontaktinformationen des Benutzers
    • completion: Die Callback-Funktion

Beispielaufruf

              
                    let user = {
          completion: (code, message)=>{ },
          contacts: {}
       }
      user.contacts["Name der Kontaktart"] = "Kontaktwert"   // Zum Beispiel: mobile_phone=18800000000
      window.MAInterface.setUserContact(user)

            

Kanal-Kontakt-ID festlegen

Unterstützte Versionen

Unterstützt ab: 2.1.0

Schnittstellen-Definition

• setChannelValue(channelId, values, completion)
  • Schnittstellen-Beschreibung:
    • Legt die RID oder das Token für einen in der MA-Konsole konfigurierten Push-Kanal (z. B. WebPush oder Drittanbieter-Push) fest.
    • Muss nach erfolgreicher SDK-Initialisierung aufgerufen werden; andernfalls gibt completion -1 zurück.
    • Ändert sich die RID oder das Token, muss die Schnittstelle erneut aufgerufen werden.
  • Parameterbeschreibung
    • channelId: Die ID des in der MA-Konsole konfigurierten Push-Kanals; muss eine ganze Zahl größer als 0 sein
    • values: Array der Kanal-Kontakt-ID-Werte (z. B. RID oder Token); darf nicht leer sein, und die Array-Elemente dürfen keine leeren Strings sein
    • completion: Die Callback-Funktion; code 0 bedeutet Erfolg

Beispielaufruf

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

            

Datenerfassungsschalter

Unterstützte Versionen

Unterstützt ab: 2.2.0

Funktionsbeschreibung

Die Anwendung aktiviert oder deaktiviert die Datenerfassung des MA SDK anhand der Einwilligung des Benutzers, um die Compliance-Anforderung zu erfüllen, dass nach Ablehnung oder Widerruf der Einwilligung keine Verhaltensdaten mehr gemeldet werden dürfen.

• Deaktiviert: Erzeugung, Zwischenspeicherung und Meldung von Ereignissen, Benutzereigenschaften, UTM- und Geräteinformationen werden gestoppt. Initialisierung, Abrufen von EUID/RID, Festlegen der Benutzerkennung, Festlegen der Kontaktinformationen und Festlegen der Kanal-Kontakt-ID bleiben wie gewohnt verfügbar.
• Aktiviert: Die Erfassung wird fortgesetzt; während der Deaktivierung entstandene Daten werden nicht nachgereicht.
• Standardmäßig aktiviert: Ohne Einstellung ist die Erfassung standardmäßig aktiviert, konsistent mit dem Verhalten vor dem Upgrade.
• Lokal gespeichert: Der Status wird lokal im Browser (localStorage) gespeichert und bleibt nach dem Neuladen oder erneuten Öffnen der Seite erhalten. Nach dem Löschen der Website-Daten wird der Standard wiederhergestellt.
• Die Anwendung entscheidet über den Schalter: Das SDK ermittelt nicht die Region des Benutzers, zeigt kein Einwilligungsfenster an und liest keine Consent-Management-Plattform (CMP) aus.

Schnittstellen-Definition

• init({ dataCollectionEnabled })

  • Schnittstellen-Beschreibung: Legt bei der Initialisierung den Schalterstatus für den ersten Start fest.
  • Parameterbeschreibung: true aktiviert; false deaktiviert; ohne Angabe standardmäßig aktiviert.

• setDataCollectionEnabled(enabled, completion)

  • Schnittstellen-Beschreibung: Aktiviert oder deaktiviert die Datenerfassung; wird sofort wirksam und lokal gespeichert.
  • Parameterbeschreibung:
    • enabled: true aktiviert, false deaktiviert
    • completion: Die Callback-Funktion; code 0 bedeutet Erfolg; ist der Parameter kein Boolean, wird -1 zurückgegeben
  • Hinweise zum Aufruf:
    • 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.
    • Beim Wechsel von aktiviert zu deaktiviert versucht das SDK sofort einmalig, die vor dem Wechsel entstandenen Daten zu senden (einschließlich des Endereignisses der aktuellen Sitzung); bei Fehlschlag erfolgt kein erneuter Versuch, anschließend wird der lokale Cache gelöscht.
    • Beim Wechsel von deaktiviert zu aktiviert meldet das SDK die Geräteinformationen und startet eine neue Sitzung (Meldung von el_session_start und el_page_view der aktuellen Seite).
    • Während der Deaktivierung wird die Konversionsattribution der WebPush-Push-Klicks nicht mehr erfasst.

• isDataCollectionEnabled()

  • Schnittstellen-Beschreibung: Gibt den aktuellen Schalterstatus zurück; liest nur den lokalen Status und sendet keine Netzwerkanfrage.
  • Rückgabewert: true aktiviert, false deaktiviert; wurde noch nie ein Status gespeichert, wird true zurückgegeben. Der Rückgabewert gibt den Schalterstatus des SDK wieder und bedeutet nicht, dass der Benutzer eingewilligt hat.

Verhalten der Schnittstellen während der Deaktivierung

Beispielaufruf

              
                // Ü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,
    completion: (code, msg) => {}
  })

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

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

  // Abfragen
  const enabled = window.MAInterface.isDataCollectionEnabled()

            

UTM-Parameter festlegen

Schnittstellen-Definition

• setUtmProperties(attrs:any)
  • Schnittstellen-Beschreibung:
    • UTM-Parameter sind standardisierte Ereigniseigenschaften. Wenn Entwickler:innen erkennen können, über welche Anzeige der/die Nutzer:in zur App gelangt ist, empfiehlt es sich, die UTM-Informationen zu setzen. Diese Parameter werden beim Melden von Ereignissen übermittelt. Folgende UTM-Parameter können aktuell gesetzt werden:
      • utm_source: Quelle der Werbekampagne
      • utm_medium: Medium der Werbekampagne
      • utm_term: Begriff der Werbekampagne
      • utm_content: Inhalt der Werbekampagne
      • utm_campaign: Name der Werbekampagne
      • utm_id: ID der Werbekampagne

Beispielaufruf

              
                 window.MAInterface.setUtmProperties({"utm_source":"value1"})

            

Benutzereigenschaften festlegen

Legt die Werte von Benutzereigenschaften fest. Falls eine Benutzereigenschaft noch nicht vorhanden ist, wird sie automatisch im Backend erstellt.

Benutzereigenschaften überschreiben und aktualisieren

• setProperty(user, completion)
  • Schnittstellen-Beschreibung:
    • Überschreibt und aktualisiert die Werte von Benutzereigenschaften.
    • Nur die zuletzt gemeldeten Daten werden gespeichert und ersetzen die historischen Daten, z. B. die Mitgliedsstufe des Benutzers.
    • Die Inhalte dieser Benutzereigenschaften werden in einem object gespeichert. Der Key ist der Name der Benutzereigenschaft und muss ein string sein; der Value ist der Inhalt der Benutzereigenschaft und unterstützt die Typen string, number, Array, object und object_array.
    • Bei einem Value vom Typ Array werden als Elemente derzeit nur string unterstützt; ein Array, dessen Elemente alle object sind, wird als object_array behandelt; ein Array, das object mit anderen Typen mischt, ist ungültig.
    • Existiert eine Benutzereigenschaft bereits, wird sie dabei überschrieben; andernfalls wird sie erstellt. Die Aktualisierungsregeln für object und object_array finden Sie weiter unten.
  • Beispielaufruf:

              
                 window.MAInterface.setProperty({key:"value"}, (code, message)=>{})

            

Regeln für object / object_array

Unterstützt ab: 2.1.0

• object ist ein nicht leeres einfaches Objekt, z. B. { city: "Singapore", score: 100 }; object_array ist ein Array, dessen Elemente alle nicht leere einfache Objekte sind.
• Unterfeldnamen müssen nicht leere string sein und dürfen weder . noch $ enthalten; Unterfeldwerte unterstützen string, number und string-Arrays; eine weitere Verschachtelung von object oder object_array wird nicht unterstützt.
• object verwendet eine Zusammenführungssemantik auf Unterfeldebene: Beim erneuten Setzen werden nur die diesmal übergebenen Unterfelder aktualisiert, nicht übergebene Unterfelder bleiben unverändert; null als Unterfeldwert entfernt das betreffende Unterfeld.
• object_array verwendet eine Gesamtersetzungssemantik: Beim erneuten Setzen wird das ursprüngliche Array vollständig durch das neue Array ersetzt, wobei die Array-Reihenfolge erhalten bleibt. Übergeben Sie beim erstmaligen Erstellen eines object_array ein nicht leeres Objekt-Array.
• Die Unterfeldtypen müssen mit der Definition der betreffenden Benutzereigenschaft in der MA-Konsole übereinstimmen; andernfalls gibt der Server einen Fehler zurück.

              
                 window.MAInterface.setProperty({
       profile: { city: "Singapore", score: 100 },
       addresses: [
           { id: "home", city: "Singapore" },
           { id: "office", city: "Tokyo" }
       ]
   }, (code, message)=>{})

   // Nur profile.score aktualisieren, profile.city bleibt unverändert
   window.MAInterface.setProperty({ profile: { score: 200 } }, (code, message)=>{})

            

Benutzereigenschaften inkrementell aktualisieren

• increaseProperty(user, completion)
  • Schnittstellen-Beschreibung:
    • Erhöht die Werte von Benutzereigenschaften kumulativ.
    • Fügt mehreren numerischen Benutzereigenschaften Werte hinzu. Alle gemeldeten Daten werden akkumuliert, z. B. der kumulierte Umsatzbetrag.
    • Diese Schnittstelle kann nur für Benutzereigenschaften vom Typ number aufgerufen werden; andernfalls wird sie ignoriert. Existiert die Benutzereigenschaft noch nicht, wird der Anfangswert als 0 behandelt.
  • Beispielaufruf:

              
               window.MAInterface.increaseProperty({key:1}, (code, message)=>{})

            

Benutzereigenschaften anhängen

• addProperty(key, content completion)
  • Schnittstellen-Beschreibung:
    • Hängt Werte an eine Benutzereigenschaft an.
    • Die Elemente dieser Menge können fortlaufend hinzugefügt werden; beim Speichern werden Duplikate entfernt. Existiert bereits ABC und wird CD angehängt, ergibt sich ABCD, z. B. die vom Benutzer gelikten Nachrichten.
    • Fügt einer Eigenschaft vom Typ Array Werte hinzu. Die Elemente dieses Arrays müssen string sein, andernfalls werden sie ignoriert. Existiert die anzuhängende Benutzereigenschaft noch nicht, wird ein leeres Array initialisiert.
  • Beispielaufruf:

              
               window.MAInterface.addProperty("key",["value1", "value2"], (code, message)=>{})

            

Benutzereigenschaften entfernen

• removeProperty(key, content completion)
  • Schnittstellen-Beschreibung:
    • Löscht einen oder mehrere Werte aus einer Eigenschaft vom Typ Array.
    • Löscht einige Werte aus einer Eigenschaft vom Typ Array. Die Elemente dieses Arrays müssen string sein, andernfalls werden sie ignoriert. Existiert die Benutzereigenschaft, deren Werte entfernt werden sollen, noch nicht, hat der Aufruf keine Wirkung.
  • Beispielaufruf:

              
               window.MAInterface.removeProperty("key",["value1", "value2"], (code, message)=>{})

            

Elemente eines object_array bearbeiten

Unterstützte Versionen

Unterstützt ab: 2.1.0

Die folgenden Verwendungen gelten nur für Benutzereigenschaften vom Typ object_array; ein Element im Array wird über ein eindeutig identifizierendes Unterfeld lokalisiert. Wird addProperty oder removeProperty ein string-Array übergeben, gelten sie weiterhin für string-Arrays, und ihr Verhalten bleibt unverändert.

• addProperty(key, object, completion)
  • Schnittstellen-Beschreibung:
    • Wird als zweiter Parameter ein einzelnes object (kein Array) übergeben, wird ein Element am Ende des object_array angehängt, ohne bestehende Elemente zu beeinflussen.
    • Das object muss ein nicht leeres Objekt sein; die Unterfeldregeln entsprechen denen des Typs object, verschachtelte object oder object_array werden nicht unterstützt.
    • Ist die Eigenschaft in der MA-Konsole noch nicht definiert, erstellt der Server sie automatisch als Eigenschaft vom Typ object_array und schreibt dieses Element; ist die Eigenschaft definiert, der aktuelle Benutzer hat aber noch keinen Wert, wird das Array mit diesem einen Element erstellt.
  • Beispielaufruf:

              
               window.MAInterface.addProperty("addresses", { id: "school", city: "Osaka" }, (code, message)=>{})

            

• updateProperty(key, content, completion)
  • Schnittstellen-Beschreibung:
    • Lokalisiert über ein eindeutig identifizierendes Unterfeld ein Element im object_array und aktualisiert dessen Unterfelder durch Zusammenführung.
    • content hat die Struktur { $identifier_key, $identifier_value, $new_object }:
      • $identifier_key: Name des Unterfelds, über das das Element lokalisiert wird; dieses Unterfeld muss in der MA-Konsole bereits definiert sein und vom Typ string oder number sein
      • $identifier_value: Lokalisierungswert vom Typ string oder number; treffen mehrere Elemente zu, wird die Aktualisierung auf alle angewendet
      • $new_object: Die zu aktualisierenden Unterfelder; muss ein nicht leeres Objekt sein und darf das zu$identifier_key gehörende Unterfeld nicht enthalten; nicht übergebene Unterfelder bleiben unverändert, null als Unterfeldwert entfernt das betreffende Unterfeld
    • Gibt es im Array kein passendes Element oder entsprechen die Unterfelder nicht der Eigenschaftsdefinition, gibt der Server einen Fehler zurück und ändert keine anderen Elemente; treffen mehrere Elemente zu, wird dieselbe Aktualisierung auf alle passenden Elemente angewendet.
    • Ist die Eigenschaft noch nicht definiert, gibt der Server einen Fehler (55004) zurück; ist sie definiert, der aktuelle Benutzer hat aber noch keinen Wert für diese Eigenschaft, gibt der Server code=0 zurück, nimmt aber keine Änderung vor.
  • Beispielaufruf:

              
               // city des Elements mit id home auf Tokyo aktualisieren und das Unterfeld zip entfernen
 window.MAInterface.updateProperty("addresses", {$identifier_key:"id", $identifier_value:"home", $new_object:{city:"Tokyo", zip:null}}, (code, message)=>{})

            

• removeProperty(key, content, completion)
  • Schnittstellen-Beschreibung:
    • Wird als zweiter Parameter { $identifier_key, $identifier_value } übergeben, wird das passende Element als Ganzes aus dem object_array entfernt (treffen mehrere Elemente zu, werden alle passenden Elemente entfernt); content darf nur diese beiden Felder enthalten.
    • Die Anforderungen an $identifier_key und$identifier_value entsprechen denen von updateProperty.
    • Ist die Eigenschaft noch nicht definiert, gibt der Server einen Fehler (55004) zurück; hat der aktuelle Benutzer keinen Wert für diese Eigenschaft oder gibt es kein passendes Element, ignoriert der Server die Anfrage und gibt code=0 zurück; treffen mehrere Elemente zu, werden alle passenden Elemente entfernt.
  • Beispielaufruf:

              
               // Element mit id office entfernen
 window.MAInterface.removeProperty("addresses", {$identifier_key:"id", $identifier_value:"office"}, (code, message)=>{})

            

Benutzereigenschaften löschen

Schnittstellen-Definition

• deleteProperty(key, completion)
  • Schnittstellen-Beschreibung:
    • Löscht den gesamten Value-Inhalt einer Benutzereigenschaft.
    • Existiert die Benutzereigenschaft noch nicht, wird der Aufruf direkt ignoriert.

Beispielaufruf

              
               window.MAInterface.deleteProperty("key", (code, message)=>{})

            

Sitzungs-Timeout festlegen

Schnittstellen-Definition

• setSessionTimeout(time)
  • Schnittstellen-Beschreibung:
    • Legt das Sitzungs-Timeout fest. Wird die Seite in den Hintergrund verschoben, beginnt die Berechnung des Sitzungs-Timeouts. Wird die festgelegte Zeit (Standard: 30 Minuten) überschritten, endet die aktuelle Sitzung.

Beispielaufruf

              
               window.MAInterface.setSessionTimeout(60)

            

Seitenverweildauer festlegen

Schnittstellen-Definition

• setPageStayTime(time)
  • Schnittstellen-Beschreibung:
    • Legt die Dauer der Seitenverweildauer fest.
    • Die Zeitmessung beginnt mit dem Seitenaufruf. Bleibt der/die Nutzer:in time Sekunden auf der Seite, ohne sie zu verlassen, wird das Ereignis gemeldet.
    • Standardmäßig wird zu den 6 Zeitpunkten 5 Sekunden, 30 Sekunden, 60 Sekunden, 2 Minuten, 5 Minuten und 10 Minuten gemeldet. Entwickler:innen können mit dieser Schnittstelle weitere Zeitpunkte hinzufügen

Beispielaufruf

              
               window.MAInterface.setPageStayTime(60)

            

Ereignis melden

Wird ein noch nicht existierendes Ereignis direkt gemeldet, wird es im Backend automatisch erstellt

Schnittstellen-Definition

• onEvent(event)
  • Schnittstellen-Beschreibung:
    • Meldet ein Ereignis
  • Parameterbeschreibung
    • event: Das zu meldende Ereignis. name ist der Ereignisname, properties enthält die Ereigniseigenschaften, wobei der Key der Eigenschaftsname und der Value der Eigenschaftswert ist

Beispielaufruf

              
                 let event = {name:"name", properties:{key:"value"}}
    window.MAInterface.onEvent(event)