SDK API Guide

Benutzerkennung festlegen

Schnittstellen-Definition

• identifyAccount(user);
  • Schnittstellen-Beschreibung:
    • Legt die Benutzerkennung fest, z. B. eine Mitgliedskartennummer.
  • Parameterbeschreibung:
    • identity: Die Benutzerkennung.
    • completion: Die Callback-Funktion.

Beispielaufruf

              
                  let user = {completion: (code, message) => {}, identity: {"id": "value"}}
    window.MAInterface.identifyAccount(user)

            

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 Schlüssel steht für die Kontaktart, der Wert für den Kontaktwert. Aktuell werden vier Kontaktarten unterstützt: email, mobile_phone, landline_phone und whatsapp_phone.
  • Parameterbeschreibung:
    • contacts: Die Kontaktinformationen des Benutzers.
    • completion: Die Callback-Funktion.

Beispielaufruf

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

            

UTM-Parameter festlegen

Schnittstellen-Definition

• setUtmProperties(attrs:any)
  • Schnittstellen-Beschreibung:
    • UTM-Parameter sind standardisierte Ereignisparameter. Wenn Entwickler:innen erkennen können, über welche Anzeige der/die Nutzer:in zur App gelangt ist, sollten die UTM-Informationen gesetzt werden. Diese Parameter werden beim Erfassen von Ereignissen übermittelt. Folgende UTM-Parameter können 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 Eigenschaft 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 der zuletzt gemeldete Wert wird gespeichert und ersetzt den bisherigen Wert, z. B. die Mitgliedsstufe des Benutzers.
    • Die Benutzereigenschaften werden als Objekt gespeichert. Der Schlüssel ist der Name der Eigenschaft (String). Der Wert kann String, Zahl oder Array sein.
    • Bei Array-Typen sind nur Strings als Elemente erlaubt.
    • Existiert die Eigenschaft bereits, wird sie überschrieben; andernfalls wird sie neu erstellt.
  • Beispielaufruf:

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

            

Benutzereigenschaften inkrementell aktualisieren

• increaseProperty(user, completion)
  • Schnittstellen-Beschreibung:
    • Erhöht die Werte numerischer Benutzereigenschaften.
    • Fügt mehreren numerischen Eigenschaften Werte hinzu und akkumuliert diese, z. B. den kumulierten Verbrauch.
    • Diese Schnittstelle ist nur für numerische Eigenschaften gültig; andere werden ignoriert. Existiert die Eigenschaft noch nicht, ist der Anfangswert 0.
  • Beispielaufruf:

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

            

Benutzereigenschaften anhängen

• addProperty(key, content, completion)
  • Schnittstellen-Beschreibung:
    • Hängt Werte an bestehende Array-Eigenschaften an.
    • Elemente werden fortlaufend hinzugefügt; doppelte Einträge werden in der Datenbank entfernt. Existiert die Eigenschaft noch nicht, wird ein leeres Array initialisiert.
    • Nur Strings als Array-Elemente werden akzeptiert.
  • Beispielaufruf:

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

            

Benutzereigenschaften entfernen

• removeProperty(key, content, completion)
  • Schnittstellen-Beschreibung:
    • Entfernt einen oder mehrere Werte aus einer Array-Eigenschaft.
    • Nur Strings als Array-Elemente werden akzeptiert. Existiert die Eigenschaft noch nicht, bleibt der Aufruf ohne Wirkung.
  • Beispielaufruf:

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

            

Benutzereigenschaften löschen

Schnittstellen-Definition

• deleteProperty(key, completion)
  • Schnittstellen-Beschreibung:
    • Löscht den gesamten Inhalt einer Benutzereigenschaft.
    • Existiert die Eigenschaft nicht, hat dies keine Auswirkung.

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, wird das Timeout gestartet. Wird die festgelegte Zeit (Standard: 30 Minuten) überschritten, endet die 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 mindestens die angegebene Zeit auf der Seite, wird das Ereignis gemeldet.
    • Standardmäßig wird bei 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

Falls ein Ereignis noch nicht existiert, wird es direkt gemeldet und im Backend automatisch erstellt.

Schnittstellen-Definition

• onEvent(event)
  • Schnittstellen-Beschreibung:
    • Meldet ein Ereignis.
  • Parameterbeschreibung:
    • event: Das zu erfassende Ereignis. name ist der Ereignisname, properties enthält die Ereigniseigenschaften (Schlüssel = Eigenschaftsname, Wert = Eigenschaftswert).

Beispielaufruf

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