iOS SDK API

iOS SDK API – Schnittstellenbeschreibung

1. MTMAService: Enthält sämtliche Schnittstellen rund um die MA-Funktionalität im SDK.
2. MTMAConfig: Klasse für Konfigurationsinformationen der Anwendung.
3. MTMAUserID: Modell zur Benutzeridentifikation.
4. MTMAUserContact: Modell für Benutzerkontaktinformationen.
5. MTMACollectControl: Modell zur Steuerung der Datenerfassung.

MA-Business-Funktion starten

Unterstützte Versionen

Ab Version 5.0.0 unterstützt

Schnittstellendefinition

• + start:(MTMAConfig * )config;
  • Beschreibung:
    • Aktiviert die EngageLab MA-Funktion.
    • Die Start-Schnittstelle dient als Einstiegspunkt und muss vor allen anderen Funktionen aufgerufen werden.
  • Parameter:
    • config: Konfigurationsklasse

Beispielaufruf

              
                  MTMAConfig *config = [[MTMAConfig alloc] init];
    [MTMAService start:config];

            

Benutzerkontaktinformationen setzen

Unterstützte Versionen

Ab Version 5.0.0 unterstützt

Schnittstellendefinition

• + (void)setUserContact:(MTMAUserContact * )contact;
  • Beschreibung:
    • Setzt die Kontaktinformationen des Benutzers/der Benutzerin.
  • Parameter:
    • contacts: Mehrere Kontaktinformationen als Dictionary. Der Schlüssel ist der Name der Kontaktinformation, der Wert ist die jeweilige Information. Unterstützt werden aktuell vier Typen: email, mobile_phone, landline_phone und whatsapp_phone.

Beispielaufruf

              
                  MTMAUserContact *contact = [[MTMAUserContact alloc] init];
    contact.contacts = @{@"Work Mobile Phone":@"13*********"};
    contact.completion = ^(NSInteger code, NSString * _Nonnull message) { };
    [MTMAService setUserContact:contact];

            

Ereignis-Reporting

Unterstützte Versionen

Ab Version 5.0.0 unterstützt

Schnittstellendefinition

• **+ (void)eventRecord:(MTMAEventObject )event;*
  • Beschreibung:
    • Erfasst ein Ereignis.
  • Parameter:
    • Ereignis-Reporting-Modell
    • eventName: Name des gemeldeten Ereignisses
    • property: Ereigniseigenschaften, wobei der Schlüssel den Eigenschaftsnamen und der Wert den Eigenschaftswert darstellt

Beispielaufruf

              
                  MTMAEventObject *object = [[MTMAEventObject alloc] init];
    object.eventName = @"sndefineevent2";
    object.property = @{
        @"key1":@"value1",
        @"key2":@"value2",
    };
    [MTMAService eventRecord:object];

            

Benutzeridentifikation setzen

Unterstützte Versionen

Ab Version 5.0.0 unterstützt

Schnittstellendefinition

• + (void)identifyAccount:(MTMAUserID * )userID;
  • Beschreibung:
    • Setzt die Benutzeridentifikation.
  • Parameter:
    • Benutzeridentifikationsmodell
    • userID: Hier die eindeutige Benutzeridentifikation für eingeloggte Nutzer:innen setzen.
    • anonymousID: Für nicht eingeloggte Nutzer:innen, aber mit anderen identifizierbaren Informationen, kann hier eine anonyme ID gesetzt werden, z. B. eine E-Mail-Adresse oder eine von Dritten generierte ID.

Beispielaufruf

              
                  MTMAUserID *userid = [[MTMAUserID alloc] init];
    userid.anonymousID = @"xxx";
    userid.userID = @"xxx";
    [MTMAService identifyAccount:userid];

            

Berichtsintervall für hochgeladene Daten festlegen

Unterstützte Versionen

Ab Version 5.0.0 unterstützt

Schnittstellendefinition

• + (void)setReportInterval:(NSInteger)interval;
  • Beschreibung:
    • Legt das Berichtsintervall für hochgeladene Daten fest. Wird diese Schnittstelle nicht aufgerufen, erfolgt die Ereignisübertragung standardmäßig alle 10 Sekunden.
    • Das Berichtsintervall wird im Speicher gehalten und muss bei jedem App-Start neu gesetzt werden.
  • Parameter:
    • interval: Berichtsintervall in Sekunden (s)

Beispielaufruf

              
                  [MTMAService setReportInterval:10];

            

Obergrenze für Ereignis-Cache-Einträge festlegen

Unterstützte Versionen

Ab Version 5.0.0 unterstützt

Schnittstellendefinition

• + (void)setMaxEventCacheCount:(NSInteger)count;
  • Beschreibung:
    • Legt die Obergrenze für die Anzahl der Ereignis-Cache-Einträge fest (Standard: 50, maximal: 500).
    • Wird die Obergrenze überschritten, werden alle Daten gemeldet.
  • Parameter:
    • count: Obergrenze der Ereignis-Cache-Einträge

Beispielaufruf

              
                  [MTMAService setMaxEventCacheCount:50];

            

Sitzungs-Timeout festlegen

Unterstützte Versionen

Ab Version 5.0.0 unterstützt

Schnittstellendefinition

• + (void)setNoActiveSessionEndDurationTime:(NSInteger)interval;
  • Beschreibung:
    • Legt das Sitzungs-Timeout fest (Standard: 30 Minuten).
    • Beim Wechsel der App in den Hintergrund startet der Timeout-Timer. Erfolgt innerhalb des Zeitraums keine Aktivität, endet die aktuelle Sitzung.
  • Parameter:
    • interval: Timeout-Dauer in Sekunden (s)

Beispielaufruf

              
                  [MTMAService setNoActiveSessionEndDurationTime:50];

            

EUID abrufen

Unterstützte Versionen

Ab Version 5.0.0 unterstützt

Schnittstellendefinition

• + (NSString * )EUID;
  • Beschreibung:
    • Gibt die EUID von EngageLab MA zurück.

Beispielaufruf

              
                  [MTMAService EUID];

            

UTM-Properties setzen

Unterstützte Versionen

Ab Version 5.0.0 unterstützt

Schnittstellendefinition

• + (void)setUtmProperties:(NSDictionary * )property;
  • Beschreibung:
    • UTM-Properties sind standardisierte Ereigniseigenschaften. Können Entwickler:innen nachvollziehen, über welche Anzeige der:die Nutzer:in zur App gelangt ist, sollten die UTM-Informationen gesetzt werden. Diese werden beim Reporting von Ereignissen übergeben. Folgende UTM-Properties 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

              
                     [MTMAService setUtmProperties:@{@"utm_source":@"value"}];

            

Benutzer-Properties setzen

Benutzer-Properties überschreiben und aktualisieren

• + (void)setProperty:(NSDictionary * )userinfo completion:(void (^)(NSInteger code, NSString * message))completion;
  • Beschreibung:
    • Diese Benutzer-Properties werden in einem NSDictionary gespeichert. Der Schlüssel ist der Name des Benutzer-Properties (NSString), der Wert kann NSString, NSNumber, NSSet oder NSArray sein.
    • Elemente in NSSet oder NSArray dürfen nur NSString sein.
    • Existiert ein Property bereits, wird es überschrieben; existiert es nicht, wird es angelegt (z. B. Mitgliedschaftsstufe).
  • Beispielaufruf:

              
                 [MTMAService setProperty:@{@"key":@"value"} completion:^(NSInteger code, NSString * _Nonnull message) {
       
   }];

            

• + (void)setProperty:(NSString * )key to:(id)value completion:(void (^)(NSInteger code, NSString * message))completion;
  • Beschreibung:
    • Setzt den Wert eines einzelnen Benutzer-Properties.
    • Die Regeln entsprechen der obigen Methode.
  • Beispielaufruf:

              
                 [MTMAService setProperty:@"key" to:@"value" completion:^(NSInteger code, NSString * _Nonnull message) {
       
   }];

            

Benutzer-Properties inkrementieren und aktualisieren

• **+ (void)increaseProperty:(NSString )key by:(NSNumber )amount completion:(void (^)(NSInteger code, NSString * message))completion;
  • Beschreibung:
    • Erhöht einen numerischen Benutzer-Property-Wert und akkumuliert alle gemeldeten Daten, z. B. kumulierter Umsatz.
    • Nur für NSNumber-Properties; existiert das Property nicht, wird es mit 0 initialisiert.
  • Beispielaufruf:

              
                  [MTMAService increaseProperty:@"key" by:@(2) completion:^(NSInteger code, NSString * _Nonnull message) {
    
    }];

            

• **+ (void)increaseProperty:(NSDictionary )userinfo completion:(void (^)(NSInteger code, NSString * message))completion;*
  • Beschreibung:
    • Erhöht mehrere numerische Benutzer-Properties.
    • Nur für NSNumber-Properties; existiert das Property nicht, wird es mit 0 initialisiert.
  • Beispielaufruf:

              
                  [MTMAService increaseProperty:@{@"key1":@(5),@"key2":@(3)} completion:^(NSInteger code, NSString * _Nonnull message) {
    
    }];

            

Benutzer-Properties hinzufügen

• **+ (void)addProperty:(NSString )key by:(NSObject )content completion:(void (^)(NSInteger code, NSString * message))completion
  • Beschreibung:
    • Fügt Werte zu einem Property vom Typ NSSet oder NSArray hinzu.
    • Die Elemente müssen NSString sein. Existiert das Property noch nicht, wird ein leeres NSSet oder NSArray initialisiert.
  • Beispielaufruf:

              
                  [MTMAService addProperty:@"key" by:@[@"value"] completion:^(NSInteger code, NSString * _Nonnull message) {
    
    }];

            

• **+ (void)addProperty:(NSDictionary )userinfo completion:(void (^)(NSInteger, NSString * _Nonnull))completion;*
  • Beschreibung:
    • Fügt mehreren Properties Werte hinzu (nur NSSet/NSArray mit NSString-Elementen).
    • Existiert das Property nicht, wird es initialisiert.
  • Beispielaufruf:

              
                  [MTMAService addProperty:@{@"key1":@[@"value"],@"key2":@[@"value"]} completion:^(NSInteger code, NSString * _Nonnull message) {
    
    }];

            

Benutzer-Properties entfernen

• **+ (void)removeProperty:(NSString * )key by:(NSObject )content completion:(void (^)(NSInteger code, NSString * message))completion;*
  • Beschreibung:
    • Entfernt Werte aus einem Property vom Typ NSSet oder NSArray.
    • Der Parameter content muss NSSet oder NSArray mit NSString-Elementen sein.
  • Beispielaufruf:

              
                  [MTMAService removeProperty:@"key" by:@[@"value"] completion:^(NSInteger code, NSString * _Nonnull message) {
    
    }];

            

Benutzer-Properties löschen

Unterstützte Versionen

Ab Version 5.0.0 unterstützt

Schnittstellendefinition

• + (void)deleteProperty:(NSString * )key completion:(void (^)(NSInteger code, NSString * message))completion;
  • Beschreibung:
    • Löscht den gesamten Inhalt eines bestimmten Benutzer-Properties.
    • Existiert das Property nicht, wird der Aufruf ignoriert.

Beispielaufruf

              
                  [MTMAService deleteProperty:@"key" completion:^(NSInteger code, NSString * _Nonnull message) {
        
    }];

            

Steuerung der Datenerfassung

Unterstützte Versionen

Ab Version 5.0.0 unterstützt

Schnittstellendefinition

• **+ (void)setCollectControl:(MTMACollectControl )control;*
  • Beschreibung:
    • Steuert, ob die in der Klasse MTMACollectControl definierten Daten gesammelt werden.

Beispielaufruf

              
                  MTMACollectControl *collectControl = [[MTMACollectControl alloc] init];
    collectControl.idfa = YES;
    collectControl.idfv = YES;
    collectControl.carrier = YES;
    [MTMAService setCollectControl:collectControl];

            

MTMAConfig-Klasse

Klasse für Konfigurationsinformationen der Anwendung. Nachfolgend die Beschreibung der Eigenschaften:

MTMAUserID-Klasse

Modellklasse für die Benutzeridentifikation. Nachfolgend die Beschreibung der Eigenschaften:

MTMACollectControl-Klasse

Modellklasse zur Steuerung der Datenerfassung. Nachfolgend die Beschreibung der Eigenschaften:

MTMAUserContact-Klasse

Modellklasse für Benutzerkanäle. Nachfolgend die Beschreibung der Eigenschaften:
Wird nicht gesetzt oder auf nil gesetzt, gilt dies als keine Änderung. Wird ein leerer String („“) gesetzt, werden die Kontaktinformationen gelöscht.

MTMAEventObject-Klasse

Klasse für benutzerdefinierte Ereignisse. Nachfolgend die Beschreibung der Eigenschaften: