Kontakt zur INFOnline

Service Center im Überblick

Sie erreichen uns montags bis freitags zwischen 09:00 Uhr – 18:00 Uhr

Customer Service | e-Mail | 0228 / 41 0 29 77

Service Center IVW digital | e-Mail | 0800 / 58 91 788 

agof service center | e-Mail | 0800 / 41 0 29 77

MMC Service Center Webradio | e-Mail | 0800 / 41 0 29 29

Usercentrics | e-Mail

SZM-Library Funktionen

Sie sind hier:

Die SZM-Library für iOS bietet die im Folgenden beschriebenen Funktionen:

Aufruf der Default Session

Alle im Folgenden beschriebenen Funktionen der SZM Library müssen auf dem Default Session Objekt aufgerufen werden. Dabei muss der SessionType als Parameter übergeben werden.

Parameter:

  • IOLSessionType (mandatory)

 
Der Typ der zu verwendenden Session. Für die SZM-Messung muss IOLSessionTypeSZM verwendet werden!


Beispiel:

Objective-C:

+(IOLSession*)defaultSessionFor:(IOLSessionType)sessionType;
IOLSession *session = [IOLSession defaultSessionFor:IOLSessionTypeSZM];

Hinweis

Für die SZM-Messung muss als sessionType IOLSessionTypeSZM übergeben werden.

Swift:

class func defaultSession(for sessionType: IOLSessionType) -> IOLSession
let session = IOLSession.defaultSession(for: .SZM)

Hinweis

Für die SZM-Messung muss als sessionType .SZM übergeben werden.

Start einer Session

Hinweis

Die IOLib muss vor der Erfassung der Events gestartet werden. Dabei müssen die Angebotskennung der App sowie die Datenschutz-Einstellung als Parameter übergeben werden.

Parameter:

  • Angebotskennung (mandatory)
    Eine eindeutige Kennung des Angebots der jeweiligen App. Die Angebotskennung wird von INFOnline pro App und pro Betriebssystem eindeutig vergeben.
  • Datenschutz-Einstellung (mandatory)
    Die Begründung, warum gemessen wird. Die möglichen Werte sind fest vorgegeben.

 
Beispiel (hier ist die Angebotskennung “iamtest” und die Datenschutz Einstellung „LIN“):

Objective C:

- (void)startSessionWithOfferIdentifier:(NSString*)offerID privacyType:(IOLPrivacyType)privacyType;
[session startSessionWithOfferIdentifier:@„iamtest“ privacyType:IOLPrivacyTypeLIN];

Swift:

func start(withOfferIdentifier offerIdentifier: String, privacyType: IOLPrivacyType)
session.start(withOfferIdentifier: „iamtest“, privacyType: .LIN)

Logging eines Events

Die Messdaten werden mittels des Aufrufs logEvent erfasst. Dabei muss ein zuvor initialisiertes Event übergeben werden.

Objective C:

- (void)logEvent:(IOLEvent*)event;


Swift:

func logEvent(_ event: IOLEvent)

Um ein Event zu erzeugen, muss ein Initializer der entsprechenden IOLEvent-Subklasse aufgerufen werden. Dabei können bis zu vier Parameter übergeben werden, drei davon sind optional.

Objective C:

- (IOL_xy_Event*)initWithType:(IOL_xy_EventType)type;
- (IOL_xy_Event*)initWithType:(IOL_xy_EventType)type category:(nullable NSString*)category comment:(nullable NSString*)comment;
- (IOL_xy_Event*)initWithType:(IOL_xy_EventType)type category:(nullable NSString*)category comment:(nullable NSString*)comment parameter:(nullable NSDictionary*)parameter;

Swift:

public init(type: IOL_xy_EventType) -> IOL_xy_Event
public init(type: IOL_xy_EventType, category: String?, comment: String?) -> IOL_xy_Event
public init(type: IOL_xy_EventType, category: String?, comment: String?, parameter: [String: String]?) -> IOL_xy_Event

Die ersten beiden Aufrufe sind Convenience-Funktionen, welche intern die Letztgenannte aufrufen.

Die fehlenden Werte werden dann um nil bzw. Default-Werte ergänzt.

Einige der Events werden durch die IOLib automatisch erfasst. Weitere Details hierzu finden sich in Kapitel 4.3.1 (Automatisch durch die SZM-Library gemessene Events).

Parameter:

  • EventType (mandatory)
    Die einzelnen Events können verschiedene Zustände einnehmen. So kann ein Download z.B. gestartet, durch den User abgebrochen, erfolgreich durchgeführt oder fehlerhaft beendet worden sein.
     
    Bei einigen Events entfällt der type Parameter, da für diese Events nur ein gültiger Type definiert ist. Beim IOLCustomEvent wird statt eines type der frei definierbare String Parameter name benötigt.
     
  • Category (optional): Inhaltscode
    Der Inhaltscode wird im Parameter “category“ übermittelt. Dieser Code wird vom Anbieter selbst festgelegt. Die syntaktischen Vorgaben sind Kapitel 4.2 (Richtlinien zur Vergabe der Codes) zu entnehmen. Der Code dient zur inhaltlichen Kennzeichnung des angezeigten Content und wird vom Anbieter im INFOnline Kundencenter dem IVW Kategoriensystem 2.0 zugeordnet.
     
    Der Anbieter entscheidet anhand der im Kapitel 4 (Vorgaben zum Aufruf der SZM-Library) beschriebenen Richtlinien, ob ein Event eine mobile PI im Sinne der IVW Richtlinien darstellt. Wenn ein Event unter die Definition einer mobilen PI fällt, ist zwingend ein Inhaltscode mitzugeben. Stellt ein Event keine mobile PI dar, soll nil übergeben werden. Die Länge dieses Feldes ist auf 255 Zeichen beschränkt.
     
  • Kommentar (optional)
    Kommentarfeld. Die Länge dieses Feldes ist nicht beschränkt.

    Übergabe dieses Wertes ist optional, ist er nicht definiert, soll nil übergeben werden.
     
  • Parameter (optional)
    Ein Dictionary mit frei bestimmbaren Zusatzinformationen zu dem Event. Key und Value müssen vom Typ String sein, die maximale Länge ist jeweils auf 255 Zeichen beschränkt.
     
    Übergabe dieses Wertes ist optional, ist er nicht definiert, soll nil übergeben werden.

Verfügbare Events

Die IOLib stellt folgende von „IOLEvent“ abgeleitete Event-Klassen mit den zugehörigen Types zur Verfügung:

  • IOLAdvertisementEvent
    • IOLAdvertisementEventTypeOpen
    • IOLAdvertisementEventTypeClose   
       
  • IOLAudioEvent
    • IOLAudioEventTypePlay
    • IOLAudioEventTypePause
    • IOLAudioEventTypeStop
    • IOLAudioEventTypeNext
    • IOLAudioEventTypePrevious
    • IOLAudioEventTypeReplay
    • IOLAudioEventTypeSeekBack
    • IOLAudioEventTypeSeekForward 
       
  • IOLBackgroundTaskEvent
    • IOLBackgroundTaskEventTypeStart
    • IOLBackgroundTaskEventTypeEnd 
       
  • IOLCustomEvent
    • type entfällt
    • stattdessen name (frei bestimmbarer String, auf 255 Zeichen beschränkt)
       
  • IOLDataEvent
    • IOLDataEventTypeCancelled
    • IOLDataEventTypeRefresh
    • IOLDataEventTypeSucceeded
    • IOLDataEventTypeFailed
       
  • IOLDeviceOrientationEvent
    • type entfällt (IOLDeviceOrientationEventTypeOrientationChanged)
        
  • IOLDocumentEvent
    • IOLDocumentEventTypeOpen
    • IOLDocumentEventTypeEdit
    • IOLDocumentEventTypeClose
         
  • IOLDownloadEvent
    • IOLDownloadEventTypeCancelled
    • IOLDownloadEventTypeStart
    • IOLDownloadEventTypeSucceeded
    • IOLDownloadEventTypeFailed
         
  • IOLGameEvent
    • IOLGameEventTypeAction
    • IOLGameEventTypeFinished
    • IOLGameEventTypeStarted
    • IOLGameEventTypeWon
    • IOLGameEventTypeLost
    • IOLGameEventTypeNewHighscore
    • IOLGameEventTypeNewAchievement
  • IOLGestureEvent
    • type entfällt (IOLGestureEventTypeShake)
       
  • IOLHardwareButtonEvent
    • type entfällt (IOLHardwareButtonEventTypePushed)
        
  • IOLIAPEvent
    • IOLIAPEventTypeStarted
    • IOLIAPEventTypeFinished
    • IOLIAPEventTypeCancelled
       
  • IOLLoginEvent
    • IOLLoginEventTypeSucceeded
    • IOLLoginEventTypeFailed
    • IOLLoginEventTypeLogout
        
  • IOLOpenAppEvent
    • IOLOpenAppEventTypeMaps
    • IOLOpenAppEventTypeOther
       
  • IOLPushEvent
    • type entfällt (IOLPushEventTypeReceived)
       
  • IOLUploadEvent
    • IOLUploadEventTypeCancelled
    • IOLUploadEventTypeStart
    • IOLUploadEventTypeSucceeded
    • IOLUploadEventTypeFailed
       
  • IOLVideoEvent
    • IOLVideoEventTypePlay
    • IOLVideoEventTypePause
    • IOLVideoEventTypeStop
    • IOLVideoEventTypeNext
    • IOLVideoEventTypePrevious
    • IOLVideoEventTypeReplay
    • IOLVideoEventTypeSeekBack
    • IOLVideoEventTypeSeekForward
         
  • IOLViewEvent
    • IOLViewEventTypeAppeared
    • IOLViewEventTypeRefreshed
    • IOLViewEventTypeDisappeared

Weitere Details zu den messbaren Events und der dazugehörigen States sind in Kapitel 4.3 (Events) beschrieben.

Beispiele:

  • IOLViewEvent / IOLViewEventTypeAppeared

 

Objective-C:

@implementation ViewController
- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  IOLEvent *event = [IOLViewEvent initWithState:IOLViewEventTypeAppeared
                                    category:@”Home”
                                     comment:nil];
[[IOLSession defaultSessionFor:IOLSessionTypeSZM] logEvent:event];   
  // Other Code ..
}

Swift:

class ViewController: UIViewController {
  override func viewDidAppear(_ animated: Bool) {
     super.viewDidAppear(animated)
     let event = IOLViewEvent(type: .appeared,
                       category: "Home"
                        comment: nil)
  IOLSession.defaultSession(for: .SZM).logEvent(event)
     // Other Code ..
  }
}

IOLViewEvent / IOLViewEventTypeRefreshed

Objective-C:

@implementation ViewController
- (IBAction)refresh:(id)sender {
  IOLEvent *event = [IOLViewEvent initWithState:IOLViewEventTypeRefreshed
                                    category:@”Home”
                                    comment:@"AdBanner shown"];
[[IOLSession defaultSessionFor:IOLSessionTypeSZM] logEvent:event];
  // Other Code ..
}

Swift:

class ViewController: UIViewController {
  @IBAction func refresh(sender: AnyObject) {
     let event = IOLViewEvent(type: .refreshed,
                       category: "Home"
                        comment: „AdBanner shown“)
  IOLSession.defaultSession(for: .SZM).logEvent(event)
     // Other Code ..
  }
}

IOLAudioEvent / IOLAudioEventTypePlay

Objective-C:

@implementation ViewController
- (IBAction)playMusic:(id)sender {
  IOLEvent *event = [IOLAudioEvent initWithState:IOLAudioEventTypePlay
                                    category:@”Audio”
                                    comment:@„Audio Playback"];
[[IOLSession defaultSessionFor:IOLSessionTypeSZM] logEvent:event];
  // Other Code ..
}

Swift:

class ViewController: UIViewController {
  @IBAction func playMusic(sender: AnyObject) {
     let event = IOLAudioEvent(type: .play,
                        category: "Audio"
                        comment: "Audio playback“)
  IOLSession.defaultSession(for: .SZM).logEvent(event)
     // Other Code ..
  }
}

Versand der Messdaten

- (void)sendLoggedEvents;

Die IOLib steuert den Versand der Messdaten selbständig und völlig transparent für den Enduser. Um den Versand der Daten zu forcieren, kann sendLoggedEvents aufgerufen werden. Die IOLib versucht dann, die Messdaten sofort bzw. alternativ nochmals zu versenden, sobald eine Datenverbindung aufgebaut wurde.

Beispiel:

Objective-C:

@implementation ViewController
- (IBAction)send:(id)sender {
  [[IOLSession defaultSessionFor:IOLSessionTypeSZM] sendLoggedEvents];
}

Swift:

class ViewController: UIViewController {
  @IBAction func send(sender: AnyObject) {
  IOLSession.defaultSession(for: .SZM).sendLoggedEvents()
  }
}

Session beenden

- (void)terminateSession;

Die aktive Session der IOLib kann explizit beendet werden. Dies ermöglicht ein Opt-out während der App-Laufzeit. Die bis dahin erfassten Daten werden nicht mehr versendet.

Hinweis:

Nur bei Opt-out durch den Nutzer verwenden!

Beispiel:

Objective-C:

@implementation ViewController
- (void)disableIOLSession {
  [[IOLSession defaultSessionFor:IOLSessionTypeSZM] terminateSession];
}

Swift:

class ViewController: UIViewController {
  func disableIOLSession() {
  IOLSession.defaultSession(for: .SZM).terminateSession()
  }
}

Hinweis

Die IOLib Session muss anschließend neu gestartet werden! Das Vorgehen ist in Kapitel 3.5.2 (Start einer Session) beschrieben.

Einbindung Opt-out Funktion

Den Nutzer einer App muss eine Opt-out Funktion gegeben werden. Die Implementierung obliegt dem Entwickler der jeweiligen App und sollte bei Aktivierung durch den Benutzer dazu führen, dass die SZM-Library entweder gar nicht initialisiert wird oder die laufende Session explizit beendet wird. Das Vorgehen ist in Kapitel Session beenden beschrieben.

Nach Einbindung der Funktion können die Nutzer der App das Opt-out aktivieren und deaktivieren. Sofern Opt-out aktiviert wird, wird kein Zählimpuls ausgelöst.

Hinweis

Wird die laufende Session explizit beendet, dann werden alle bis dahin erfassten, aber noch nicht versandten Messdaten verworfen.

Wird das Opt-out revidiert, dann sollte die MessLib wieder gestartet werden. Das Vorgehen ist in Kapitel Start einer Session beschrieben.

Einbindung Opt-in Funktion

Nach dem Start der App kann die Einwilligung des Nutzers zur Teilnahme an der Messung eingeholt werden. Die Implementierung obliegt dem Entwickler der jeweiligen App und soll nach der Zustimmung des Nutzers dazu führen, dass die Session gestartet wird (vergl. Kapitel „Start einer Session“). Bitte übermitteln Sie in diesem Fall das Privacy-Setting „ACK“. Beispiel (Swift): 

session.start(withOfferIdentifier: „iamtest“, privacyType: .ACK)