SZM-Library Funktionen¶

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:

1
2

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

Swift:

1
2

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

Start einer Session¶

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:

1
2

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

Swift:

1
2

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:

1
2
3

- (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:

1
2
3

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:

1
2
3
4
5
6
7
8
9

@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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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:

1
2
3
4
5
6
7
8

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

Swift:

1
2
3
4
5
6
7
8
9

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:

1
2
3
4
5
6
7
8

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

Swift:

1
2
3
4
5
6
7
8
9

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:

1
2
3
4

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

Swift:

1
2
3
4
5

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.

Beispiel:

Objective-C:

1
2
3
4

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

Swift:

1
2
3
4
5

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

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.

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)

TCF 2.0 Manuelle Verarbeitung¶

Die manuelle Verarbeitung der TCF Consent Daten werden mittels der Methode setCustomConsent durchgeführt. Dabei muss ein zuvor gemäß IO Consent String Notation gebildeter Consent String übergeben werden.

Objective-C:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

@implementation AppDelegate
- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions {
   [self startSession];
   // Other code
   return YES;
}
- (void)startSession {
  // Initialisierung der IOLib; Session-Start
  // privacySetting LIN = Berechtigtes Interesse ist gegeben
  [[IOLSession defaultSessionFor:IOLSessionTypeSZM]
    startSessionWithOfferIdentifier:@"<ANGEBOTSKENNUNG>"
    privacyType:IOLPrivacyTypeLIN];
  [[IOLSession defaultSessionFor:IOLSessionTypeSZM] 
    setCustomConsent:@"<CUSTOMCONSENT>"]; // s. IO Consent String Notation
}  

Swift:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
  self.startSession()
  // Other code
  return true
}
func startSession() {
  // Initialisierung der IOLib; Session-Start
  // privacySetting LIN = Berechtigtes Interesse ist gegeben
  IOLSession.defaultSession(for: .SZM).start(withOfferIdentifier:"<ANGEBOTSKENNUNG>", 
  privacyType: .LIN)
  IOLSession.defaultSession(for: .SZM).setCustomConsent("<CUSTOMCONSENT>") // s. IO Consent String Notation
}  

Wie bereits erwähnt, priorisiert die IOLib die automatischen Verarbeitung höher als die manuelle Verarbeitung. Ist das Ergebnis der automatischen Verarbeitung ein valider IO Consent String, wird dieser immer übermittelt und der manuelle ignoriert.

Um zur Laufzeit überprüfen zu können, welcher Consent String zur Übermittlung verwendet wird, kann die Methode consent aufgerufen werden. Diese retourniert den zur Übermittlung aktuell verwendeten IO Consent String.

Objective-C:

[IOLSession defaultSessionFor:IOLSessionTypeSZM].consent;

Swift:

IOLSession.defaultSession(for: .SZM).consent()