Android SDK API

SDK-Schnittstellenbeschreibung

• MTMAApi enthält sämtliche Schnittstellen, die sich auf die MA-Funktionalität des SDK beziehen.

Aktivierung der MA-Funktionalität

Unterstützte Versionen

Unterstützt ab Version 5.0.0

Schnittstellendefinition

• start(UserIdentity userIdentity, CallBack callBack)
  • Schnittstellenbeschreibung:
    • Startet die Nutzung der MA-Funktionalität. Die Benutzeridentifikation kann beim Aktivieren der Funktion gleichzeitig gesetzt werden.
  • Parameterbeschreibung:
    • userIdentity: Die Benutzeridentifikation, kann auf null gesetzt werden, falls nicht vorhanden.
      • setUserId(String userId): Benutzer-ID, hier die eindeutige, eingeloggte Benutzer-ID setzen.
      • setAnonymousId(String anonymousId): Anonyme ID. Wenn der Benutzer nicht eingeloggt ist, aber andere identifizierbare Informationen bereitstellt, kann hier eine anonyme ID (z. B. E-Mail-Adresse oder von Dritten generierte ID) gesetzt werden.
    • callBack: Rückgabedaten-Callback.
  • Rückgabebeschreibung:
    onCallBack(int code, String message)
    • code: Fehlercode. 0 steht für erfolgreichen Abruf, -1 für einen Fehler. Details siehe message-Parameter.
    • message: Grundbeschreibung.

Aufrufbeispiel

              
              MTMAApi.getInstance(this).start(new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
        Log.e(TAG, "start code:" + code);
        Log.e(TAG, "startmessage:" + message);
    }
});

            

Benutzeridentifikation setzen

Es wird empfohlen, diese Schnittstelle beim Login oder bei Angabe relevanter Informationen zu setzen, um die passende EUID für den jeweiligen Benutzer zu erhalten.

Unterstützte Versionen

Unterstützt ab Version 5.0.0

Schnittstellendefinition

• setUserIdentity(UserIdentity userIdentity, CallBack callBack)
  • Schnittstellenbeschreibung:
    • Setzt die Benutzeridentifikation, z. B. die Benutzer-ID des Benutzers.
  • Parameterbeschreibung:
    • userIdentity: Die Benutzeridentifikation.
      • setUserId(String userId): Benutzer-ID, hier die eindeutige, eingeloggte Benutzer-ID setzen.
      • setAnonymousId(String anonymousId): Anonyme ID. Wenn der Benutzer nicht eingeloggt ist, aber andere identifizierbare Informationen bereitstellt, kann hier eine anonyme ID (z. B. E-Mail-Adresse oder von Dritten generierte ID) gesetzt werden.
    • callBack: Schnittstellen-Callback.
  • Rückgabebeschreibung:
    onCallBack(int code, String message)
    • code: Fehlercode. 0 steht für erfolgreichen Abruf, -1 für einen Fehler. Details siehe message-Parameter.

Aufrufbeispiel

              
              UserIdentity userIdentity = new UserIdentity();
userIdentity.setUserId("Ihre userId");
userIdentity.setAnonymousId("Ihre AnonymousId");
MTMAApi.getInstance(this).setUserIdentity(userIdentity, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
        MTCommonLog.e(TAG, "setUserIdentity code:" + code);
        MTCommonLog.e(TAG, "setUserIdentity message:" + message);
    }
});

            

Benutzerkontaktinformationen setzen

Bei Änderungen der Kontaktinformationen des Benutzers kann diese Schnittstelle zur Aktualisierung der „Kontaktdaten“ verwendet werden.

Unterstützte Versionen

Unterstützt ab Version 5.0.0

Schnittstellendefinition

• setUserContact(JSONObject contacts, CallBack callBack)
  • Schnittstellenbeschreibung:
    • Setzt die „Kontaktinformationen“ des Benutzers.
  • Parameterbeschreibung:
    • contacts: Mehrere Kontaktinformationen setzen. Der Schlüssel ist der Name der Kontaktinformation, der Wert ist der Wert der Kontaktinformation. Aktuell werden 4 Typen unterstützt: email, mobile_phone, landline_phone und whatsapp_phone.
    • callBack: Schnittstellen-Callback.
  • Rückgabebeschreibung:
    onCallBack(int code, String message)
    • code: Fehlercode. 0 steht für erfolgreichen Abruf, -1 für einen Fehler. Details siehe message-Parameter.
    • message: Grundbeschreibung.

Aufrufbeispiel

              
              JSONObject contacts = new JSONObject();
try {
    contacts.put("key1", "cc");
    contacts.put("key2", "dd");
} catch (JSONException e) {
    e.printStackTrace();
}
MTMAApi.getInstance(this).setUserContact(contacts, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
        Log.e(TAG, "setUserContact code:" + code);
        Log.e(TAG, "setUserContact message:" + message);
    }
});

            

EUID abrufen

Unterstützte Versionen

Unterstützt ab Version 5.0.0

Schnittstellendefinition

• getEuid()
  • Schnittstellenbeschreibung:
    • Ruft die EUID ab, die die eindeutige Benutzer-ID darstellt.

Aufrufbeispiel

              
              MTMAApi.getInstance(this).getEuid();

            

Übertragungsintervall für hochgeladene Daten setzen

Funktioniert zusammen mit der Schnittstelle setMaxEventCacheCount. Ein Reporting erfolgt, sobald eine der Bedingungen erfüllt ist.

Unterstützte Versionen

Unterstützt ab Version 5.0.0

Schnittstellendefinition

• setReportInterval(int interval)
  • Schnittstellenbeschreibung:
    • Setzt das Übertragungsintervall für hochgeladene Daten. Wird diese Schnittstelle nicht aufgerufen, erfolgt die Ereignisübertragung standardmäßig alle 10 Sekunden.
    • Das Übertragungsintervall wird im Speicher zwischengespeichert und muss in jedem Lebenszyklus der App gesetzt werden, damit es wirksam wird.
  • Parameterbeschreibung
    • interval: Übertragungsintervall in Sekunden.

Aufrufbeispiel

              
              MTMAApi.getInstance(this).setReportInterval(10);

            

Obergrenze für Event-Cache-Einträge setzen

Wirkt zusammen mit der Schnittstelle setReportInterval. Ein Reporting erfolgt, sobald eine der Bedingungen erfüllt ist.

Unterstützte Versionen

Unterstützt ab Version 5.0.0

Schnittstellendefinition

• setMaxEventCacheCount(int count)
  • Schnittstellenbeschreibung:
    • Setzt die Obergrenze für die Anzahl der Event-Cache-Einträge. Standardwert ist 50, maximal 500.
    • Sobald die maximale Cache-Anzahl überschritten wird, werden alle zwischengespeicherten Daten übermittelt.
  • Parameterbeschreibung
    • count: Obergrenze der Event-Cache-Einträge.

Aufrufbeispiel

              
              MTMAApi.getInstance(this).setMaxEventCacheCount(50);

            

Sitzungs-Timeout setzen

Unterstützte Versionen

Unterstützt ab Version 5.0.0

Schnittstellendefinition

• setNoActiveSessionEndDurationTime(int duration)
  • Schnittstellenbeschreibung:
    • Wird die App in den Hintergrund gelegt, beginnt die Berechnung der Sitzungs-Timeout-Zeit. Nach Ablauf der eingestellten Zeit (Standard: 30 Minuten) wird die Sitzung automatisch beendet.
  • Parameterbeschreibung
    • duration: Timeout-Dauer in Sekunden.

Aufrufbeispiel

              
              MTMAApi.getInstance(this).setNoActiveSessionEndDurationTime(5*60);

            

UTM-Parameter setzen

Unterstützte Versionen

Unterstützt ab Version 5.0.0

Schnittstellendefinition

• setUtmProperties(UtmProperties utmProperties)
  • Schnittstellenbeschreibung:
    • Setzt die UTM-Parameter. Wenn Sie nachvollziehen können, über welche Anzeige ein Benutzer zur App gelangt ist, empfiehlt es sich, die UTM-Informationen zu setzen. Diese werden beim Reporting der Events übermittelt.
  • Parameterbeschreibung:
    • utmProperties: UTM-Objekt.
      • 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.

Aufrufbeispiel

              
              UtmProperties utmProperties = new UtmProperties();
utmProperties.setUtmSource("Ihr utm_source");
utmProperties.setUtmCampaign("Ihr utm_campaign");
utmProperties.setUtmContent("Ihr utm_content");
utmProperties.setUtmId("Ihr utm_id");
utmProperties.setUtmMedium("Ihr utm_medium");
utmProperties.setUtmTerm("Ihr utm_term");
MTMAApi.getInstance(this).setUtmProperties(utmProperties);

            

Erfassungserlaubnis setzen

Unterstützte Versionen

Unterstützt ab Version 5.0.0

Schnittstellendefinition

• setCollectControl(MTMACollectControl control)
  • Schnittstellenbeschreibung:
    • Setzt die Erfassungserlaubnis. Wenn Sie die Erfassung bestimmter Daten aktivieren oder deaktivieren möchten, rufen Sie diese Schnittstelle auf.
  • Parameterbeschreibung:
    • control: Berechtigungseinstellung, standardmäßig aktiviert.

Aufrufbeispiel

              
              try {
    MTMACollectControl mtmaCollectControl = new MTMACollectControl();
    mtmaCollectControl.setIMEI(true);
    mtmaCollectControl.setAAID(true);
    MTMAApi.getInstance(this).setCollectControl(mtmaCollectControl);
} catch (Throwable e) {
    e.printStackTrace();
}

            

Benutzerattribute verwalten

Sollten die Attribute noch nicht existieren, werden sie automatisch im Hintergrund angelegt.

Benutzerattribute überschreiben und aktualisieren

• propertySet(final JSONObject properties, final CallBack callBack)
  • Schnittstellenbeschreibung:
    • Aktualisiert die Werte der Benutzerattribute stapelweise durch Überschreiben.
    • Es wird nur der zuletzt gemeldete Wert gespeichert, ältere Werte werden überschrieben (z. B. Mitgliedslevel).
  • Parameterbeschreibung:
    • properties: Benutzerattribute.
    • callBack: Schnittstellen-Callback.
  • Rückgabebeschreibung:
    onCallBack(int code, String message)
    • code: Fehlercode. 0 steht für erfolgreichen Abruf, -1 für einen Fehler. Details siehe Fehlercode.
    • message: Grundbeschreibung.
  • Aufrufbeispiel:

              
              try {
    JSONObject properties = new JSONObject();
    properties.put("Ihr Benutzerattributname", "Ihr Attributwert");
    properties.put("Ihr Benutzerattributname 2", "Ihr Attributwert 2");
    properties.put("Ihr Benutzerattributname 3", "Ihr Attributwert 3");
    MTMAApi.getInstance(this).propertySet(properties, new CallBack() {
        @Override
        public void onCallBack(int code, String message) {
        }
    });
} catch (Throwable e) {
    e.printStackTrace();
}

            

• propertySet(String property, Object value, CallBack callBack)
  • Schnittstellenbeschreibung:
    • Aktualisiert den Wert eines einzelnen Benutzerattributs durch Überschreiben.
    • Es wird nur der zuletzt gemeldete Wert gespeichert, ältere Werte werden überschrieben (z. B. Mitgliedslevel).
  • Parameterbeschreibung:
    • property: Name des Benutzerattributs.
    • value: Wert des Benutzerattributs.
    • callBack: Schnittstellen-Callback.
  • Rückgabebeschreibung:
    onCallBack(int code, String message)
    • code: Fehlercode. 0 steht für erfolgreichen Abruf, -1 für einen Fehler. Details siehe Fehlercode.
    • message: Grundbeschreibung.
  • Aufrufbeispiel:

              
              MTMAApi.getInstance(this).propertySet("Ihr Benutzerattributname", "Ihr Attributwert", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

Benutzerattribute inkrementieren und aktualisieren

• propertyIncrease(final Map<String, ? extends Number> properties, CallBack callBack)
  • Schnittstellenbeschreibung:
    • Setzt eine Erhöhung für die Werte von Benutzerattributen, für Batch-Anfragen.
    • Alle gemeldeten Werte werden kumuliert, z. B. der kumulierte Verbrauchsbetrag.
    • Diese Schnittstelle kann nur für numerische Benutzerattribute aufgerufen werden, sonst wird sie ignoriert. Existiert das Attribut noch nicht, wird der Anfangswert als 0 behandelt.
  • Parameterbeschreibung:
    • properties: Benutzerattribute.
    • callBack: Schnittstellen-Callback.
  • Rückgabebeschreibung:
    onCallBack(int code, String message)
    • code: Fehlercode. 0 steht für erfolgreichen Abruf, -1 für einen Fehler. Details siehe Fehlercode.
    • message: Grundbeschreibung.
  • Aufrufbeispiel:

              
              Map<String, Number> properties = new HashMap<>();
properties.put("Ihr Benutzerattributname", 1);
properties.put("Ihr Benutzerattributname 2", 2);
properties.put("Ihr Benutzerattributname 3", 3);
MTMAApi.getInstance(this).propertyIncrease(properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

• propertyIncrease(final String property, final Number value, CallBack callBack)
  • Schnittstellenbeschreibung:
    • Setzt eine Erhöhung für den Wert eines Benutzerattributs, für eine Einzelanfrage.
    • Alle gemeldeten Werte werden kumuliert, z. B. der kumulierte Verbrauchsbetrag.
    • Diese Schnittstelle kann nur für numerische Benutzerattribute aufgerufen werden, sonst wird sie ignoriert. Existiert das Attribut noch nicht, wird der Anfangswert als 0 behandelt.
  • Parameterbeschreibung:
    • property: Name des Benutzerattributs.
    • value: Wert des Benutzerattributs.
    • callBack: Schnittstellen-Callback.
  • Rückgabebeschreibung:
    onCallBack(int code, String message)
    • code: Fehlercode. 0 steht für erfolgreichen Abruf, -1 für einen Fehler. Details siehe Fehlercode.
    • message: Grundbeschreibung.
  • Aufrufbeispiel:

              
              MTMAApi.getInstance(this).propertyIncrease("Ihr Benutzerattributname", 1, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

Benutzerattribute anhängen

• propertyAdd(final String property, final String value, CallBack callBack)
  • Schnittstellenbeschreibung:
    • Hängt einen Wert an den Wert eines Benutzerattributs an, Einzelanfrage.
    • Die Elemente dieser Menge können fortlaufend hinzugefügt werden, doppelte Elemente werden beim Speichern in der Datenbank entfernt. Wenn bereits der Wert ABC existiert und CD hinzugefügt wird, lautet das Endergebnis ABCD.
  • Parameterbeschreibung:
    • property: Name des Benutzerattributs.
    • value: Wert des Benutzerattributs.
    • callBack: Schnittstellen-Callback.
  • Rückgabebeschreibung:
    onCallBack(int code, String message)
    • code: Fehlercode. 0 steht für erfolgreichen Abruf, -1 für einen Fehler. Details siehe Fehlercode.
    • message: Grundbeschreibung.
  • Aufrufbeispiel:

              
              MTMAApi.getInstance(this).propertyAdd("Ihr Benutzerattributname", "Ihr Benutzerattributwert", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

• propertyAdd(final String property, final Set values, CallBack callBack)
  • Schnittstellenbeschreibung:
    • Hängt mehrere Werte an den Wert eines Benutzerattributs an.
    • Die Elemente dieser Menge können fortlaufend hinzugefügt werden, doppelte Elemente werden beim Speichern in der Datenbank entfernt. Wenn bereits der Wert ABC existiert und CD hinzugefügt wird, lautet das Endergebnis ABCD.
  • Parameterbeschreibung:
    • property: Name des Benutzerattributs.
    • value: Wert des Benutzerattributs.
    • callBack: Schnittstellen-Callback.
  • Rückgabebeschreibung:
    onCallBack(int code, String message)
    • code: Fehlercode. 0 steht für erfolgreichen Abruf, -1 für einen Fehler. Details siehe Fehlercode.
    • message: Grundbeschreibung.
  • Aufrufbeispiel:

              
              Set<String> properties = new HashSet<>();
properties.add("Ihr Benutzerattributwert");
properties.add("Ihr Benutzerattributwert 2");
properties.add("Ihr Benutzerattributwert 3");
MTMAApi.getInstance(this).propertyAdd("Ihr Benutzerattributname", properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

Benutzerattribute entfernen

• propertyRemove(final String property, String values, final CallBack callBack)
  • Schnittstellenbeschreibung:
    • Entfernt den Wert eines Benutzerattributs.
    • Dieser Wert ist ein Element der Menge, doppelte Elemente werden beim Speichern in der Datenbank entfernt. Wenn bereits der Wert ABCD existiert und D entfernt wird, lautet das Endergebnis ABC.
  • Parameterbeschreibung:
    • property: Name des Benutzerattributs.
    • value: Wert des Benutzerattributs.
    • callBack: Schnittstellen-Callback.
  • Rückgabebeschreibung:
    onCallBack(int code, String message)
    • code: Fehlercode. 0 steht für erfolgreichen Abruf, -1 für einen Fehler. Details siehe Fehlercode.
    • message: Grundbeschreibung.
  • Aufrufbeispiel:

              
              MTMAApi.getInstance(this).propertyRemove("Ihr Benutzerattributname", "Ihr Benutzerattributwert", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

• propertyRemove(final String property, Set values, final CallBack callBack)
  • Schnittstellenbeschreibung:
    • Entfernt mehrere Werte eines Benutzerattributs auf einmal.
    • Diese Werte sind Elemente der Menge, doppelte Elemente werden beim Speichern in der Datenbank entfernt. Wenn bereits der Wert ABCD existiert und CD entfernt werden, lautet das Endergebnis AB.
  • Parameterbeschreibung:
    • property: Name des Benutzerattributs.
    • value: Wert des Benutzerattributs.
    • callBack: Schnittstellen-Callback.
  • Rückgabebeschreibung:
    onCallBack(int code, String message)
    • code: Fehlercode. 0 steht für erfolgreichen Abruf, -1 für einen Fehler. Details siehe Fehlercode.
    • message: Grundbeschreibung.
  • Aufrufbeispiel:

              
              Set<String> properties = new HashSet<>();
properties.add("Ihr Benutzerattributwert");
properties.add("Ihr Benutzerattributwert 2");
properties.add("Ihr Benutzerattributwert 3");
MTMAApi.getInstance(this).propertyRemove("Ihr Benutzerattributname", properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

Benutzerattribute löschen

Unterstützte Versionen

Unterstützt ab Version 5.0.0

Schnittstellendefinition

• propertyDelete(final String property, final CallBack callBack)
  • Schnittstellenbeschreibung:
    • Löscht alle Werte eines bestimmten Benutzerattributs.
  • Parameterbeschreibung:
    • property: Name des Benutzerattributs.
    • callBack: Schnittstellen-Callback.
  • Rückgabebeschreibung:
    onCallBack(int code, String message)
    • code: Fehlercode. 0 steht für erfolgreichen Abruf, -1 für einen Fehler. Details siehe Fehlercode.
    • message: Grundbeschreibung.

Aufrufbeispiel

              
              MTMAApi.getInstance(this).propertyDelete("Ihr Benutzerattributname", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
    }
});

            

Benutzerdefiniertes Event-Reporting

Unterstützte Versionen

Unterstützt ab Version 5.0.0

Schnittstellendefinition

• onEvent(String eventKey, JSONObject properties)
  • Schnittstellenbeschreibung:
    • Meldet ein benutzerdefiniertes Event.
  • Parameterbeschreibung:
    • eventKey: Name des Events.
    • properties: Event-Eigenschaften. Der Schlüssel ist der Name der Eigenschaft, der Wert ist der Wert der Eigenschaft.

Aufrufbeispiel

              
              JSONObject properties = new JSONObject();
properties.put("key1", "v1");
properties.put("key2", "v2");
MTMAApi.getInstance(this).onEvent("Ihr Eventname", properties);

            

Fehlercodes