Zum Inhalt

IO-Library Funktionen

Die IOLib für Android bietet die im Folgenden beschriebenen Funktionen:

Nutzung der IOLib im SZM-Modus

IOLSession getSessionForType(IOLSessionType iolSessionType)

Funktionen der IOLib müssen auf einer konkreten IOLSession aufgerufen werden. Dazu übergibt man den entsprechenden IOLSessionType.

Parameter:

  • IOLSessionType (mandatory)
    Der gewünschte IOLSessionType.

Beispiel: IOLSession iolSession = IOLSession.getSessionForType(IOLSessionType.SZM);

Initialisierung

1
2
initIOLSession(String offerIdentifier, boolean debugModeEnabled, IOLSessionPrivacySetting privacySetting)
initIOLSession(Context context, String offerIdentifier, boolean debugModeEnabled, IOLSessionPrivacySetting privacySetting)
Hinweis

Die IOLib muss vor der Erfassung der Events initalisiert werden. Dabei muss die Angebotskennung der App als Parameter übergeben werden.

Parameter:

  • Application Context (optional)
    Der Application Context der Android App muss hier übergeben werden, falls nicht bereits über IOLSession.init(Context context) geschehen.

  • Angebotskennung (mandatory)
    Die eindeutige Kennung des Angebots der jeweiligen App. Die Angebotskennung wird von der INFOnline pro App und pro Betriebssystem eindeutig vergeben.

  • debugModeEnabled (optional)
    Wenn der Debug Modus aktiviert ist, loggt die MessLibrary unter dem logcat tag „INFOnline“. Es wird empfohlen, hier den Wert „BuildConfig.DEBUG“ zu übergeben.

    Default ist false, falls kein Wert übergeben wird.

  • Datenschutz-Einstellungen (mandatory)
    Die Begründung, warum gemessen wird. Die möglichen Werte sind fest vorgegeben.

Beispiel

1
2
3
4
5
IOLSession.getSessionForType(IOLSessionType.SZM) 
          .initIOLSession(this, // Application Context 
                          "OfferIdentifier", // Offer Identifier 
                           BuildConfig.DEBUG); // Debug mode 
                           IOLSessionPrivacySetting.LIN); // Privacy Setting LIN

Logging eines Events

Die Messdaten werden mittels des Aufrufs logEvent erfasst. Dabei wird eine Instanz der zu messenden Event Klasse übergeben.

logEvent(IOLEvent event)

Parameter:

  • Event (mandatory)
    Das zu erfassende Event.

Einige der Events werden durch die IOLib automatisch erfasst.

Weitere Details: Automatisch durch die SZM-Library gemessene Events.

Instanzierung einer Event Klasse

IOLEvent(EventType eventType, String category, String comment, Map<String, String> params)

  • EventType (mandatory):
    Das zu erfassende Event. 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. 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 folgenden Kapitel 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.

  • Comment (optional): Kommentar
    Kommentarfeld. Die Länge dieses Feldes ist nicht beschränkt. Übergabe dieses Wertes ist optional, ist er nicht definiert, soll er nicht übergeben werden.

  • params (optional): Parameter
    Eine Hash Map 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.

Verfügbare Events

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

IOLAdvertisementEvent

  • IOLAdvertisementEventType.Open
  • IOLAdvertisementEventType.Close

IOLAudioEvent

  • IOLAudioEventType.Play
  • IOLAudioEventType.Pause
  • IOLAudioEventType.Stop
  • IOLAudioEventType.Next
  • IOLAudioEventType.Previous
  • IOLAudioEventType.Replay
  • IOLAudioEventType.SeekBack
  • IOLAudioEventType.SeekForward

IOLBackgroundTaskEvent

  • IOLBackgroundTaskEventType.Start
  • IOLBackgroundTaskEventType.End

IOLCustomEvent

  • type entfällt
  • stattdessen name (frei bestimmbarer String, auf 255 Zeichen beschränkt)

IOLDataEvent

  • IOLDataEventType.Cancelled
  • IOLDataEventType.Refresh
  • IOLDataEventType.Succeeded
  • IOLDataEventType.Failed

IOLDeviceOrientationEvent

  • IOLDeviceOrientationEventType.Changed

IOLDocumentEvent

  • IOLDocumentEventType.Open
  • IOLDocumentEventType.Edit
  • IOLDocumentEventType.Close

IOLDownloadEvent

  • IOLDownloadEventType.Cancelled
  • IOLDownloadEventType.Start
  • IOLDownloadEventType.Succeeded
  • IOLDownloadEventType.Failed

IOLGameEvent

  • IOLGameEventType.Action
  • IOLGameEventType.Started
  • IOLGameEventType.Finished
  • IOLGameEventType.Won
  • IOLGameEventType.Lost
  • IOLGameEventType..NewHighscore
  • IOLGameEventTypeNewAchievement

IOLGestureEvent

  • IOLGestureEventType.Shake

IOLHardwareButtonEvent

  • IOLHardwareButtonEventType.Pushed

IOLIAPEvent

  • IOLIAPEventType.Started
  • IOLIAPEventType.Finished
  • IOLIAPEventType.Cancelled

IOLLoginEvent

  • IOLLoginEventType.Succeeded
  • IOLLoginEventType.Failed
  • IOLLoginEventType.Logout

IOLOpenAppEvent

  • IOLOpenAppEventType.Maps
  • IOLOpenAppEventType.Other

IOLPushEvent

  • IOLPushEventType.Received

IOLUploadEvent

  • IOLUploadEventType.Cancelled
  • IOLUploadEventType.Start
  • IOLUploadEventType.Succeeded
  • IOLUploadEventType.Failed

IOLVideoEvent

  • IOLVideoEventType.Play
  • IOLVideoEventType.Pause
  • IOLVideoEventType.Stop
  • IOLVideoEventType.Next
  • IOLVideoEventType.Previous
  • IOLVideoEventType.Replay
  • IOLVideoEventType.SeekBack
  • IOLVideoEventType.SeekForward

IOLViewEvent

  • IOLViewEventType.Appeared
  • IOLViewEventType.Refreshed
  • IOLViewEventType.Disappeared

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

Beispiele:

IOLEventType.ViewAppeared

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
public class SampleActivity extends Activity { 

   @Override 
   protected void onResume() { 
         super.onResume(); 
         IOLEvent event = new IOLViewEvent(
           IOLViewEvent.IOLViewEventType.Appeared, 
             "category", 
             "comment"); 
          IOLSession.getSessionForType(IOLSessionType.SZM).logEvent(event); 
         // Other Code .. 
    } 
}

IOLEventType.ViewRefreshed

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
public class SampleActivity extends Activity {

   @Override 
   protected void onResume() { 
         super.onResume(); 
         IOLEvent event = new IOLViewEvent(
             IOLViewEvent.IOLViewEventType.Refreshed,
             "category", 
             "comment"); 
          IOLSession.getSessionForType(IOLSessionType.SZM).logEvent(event); 
         // Other Code .. 
    } 
}

IOLEventType.AudioPlay

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
public class SampleActivity extends Activity {

   @Override 
   protected void onResume() { 
         super.onResume(); 
         IOLEvent event = new IOLAudioEvent( 
             IOLAudioEvent.IOLAudioEventType.Play, 
             "Audio", 
             "Audio Playback");
         IOLSession.getSessionForType(IOLSessionType.SZM).logEvent(event); 
         // Other Code .. 
    } 
}

IOLEventType.HardwareButtonPushed

Falls echte KeyEvents geloggt werden sollen, muss die Methode dispatchKeyEvent() in den entsprechenden Activities überschrieben werden:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
public class SampleActivity extends Activity { 

   @Override 
   public boolean dispatchKeyEvent (KeyEvent event){
          if(event.getAction() == KeyEvent.ACTION_UP && 
          event.getKeyCode() == KeyEvent.KEYCODE_BACK){ 

                Map customParams = new HashMap<String, String>(); 
                customParams.put("myCustomKey", "myCustomValue"); 

                IOLEvent event = new IOLHardwareButtonEvent( 
                         IOLHardwareButtonEvent.IOLHardwareButtonEventType.Pushed, 
                         "Category", 
                         "Comment", 
                         customParams);
                IOLSession.getSessionForType(IOLSessionType.SZM).logEvent(event); 
               // Other Code ..
          }
          return super.dispatchKeyEvent(event); 
}

In diesem Beispiel wird das Loslassen der BACK-Taste mit zusätzlichen Parametern gemessen.

Versand der Messdaten

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. nochmals zu versenden, sobald eine Datenverbindung aufgebaut wurde.

Beispiel

IOLSession.getSessionForType(IOLSessionType.SZM).sendLoggedEvents();

Debug Modus

setDebugModeEnabled(boolean enable);

Die Messlib kann in einen Debug-Modus versetzt werden. Hier werden diverse Ausgaben im Logstrom erzeugt (Fehler, Warnungen, Infos, Events und Requests).

Default-Wert ist false, wenn die MessLibrary mit IOLSession.initIOLSession(Context context, String offerIdentifier) initialisiert wurde.

Parameter:

  • boolean enable
    Mögliche Werte: true|false

Beispiel

IOLSession.setDebugModeEnabled(true);

Session beenden

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

Beispiel

IOLSession.getSessionForType(IOLSessionType.SZM).terminateSession();

Hinweis

Session muss anschließend nicht neu initialisiert werden, sondern kann per startSession() jederzeit gestartet werden!

Session starten

startSession()

Wurde die aktive Session der IOLib explizit beendet, kann diese jederzeit per startSession() erneut gestartet werden. Eine Neuinitialisierung ist nicht notwendig.

Beispiel

IOLSession.getSessionForType(IOLSessionType.SZM).startSession();

Einbindung Opt-out Funktion

Dem 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 „Session starten“ 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 Library initialisiert wird (vergl. Kapitel „initialisierung“).

Bitte übermitteln Sie in diesem Fall das Privacy-Setting „ACK“.

Beispiel:

1
2
3
4
5
IOLSession.getSessionForType(IOLSessionType.SZM) 
          .initIOLSession(this, // Application Context 
                          "OfferIdentifier", // Offer Identifier 
                           BuildConfig.DEBUG); // Debug mode 
                           IOLSessionPrivacySetting.ACK); // Privacy Setting ACK

TCF 2.0 Manuelle Verarbeitung

D ie 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.

Beispiel:

1
2
3
IOLSession session = IOLSession.getSessionForType(SessionType.SZM);
// Set custom consent:
session.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 getConsent aufgerufen werden. Diese retourniert den zur Übermittlung aktuell verwendeten IO Consent String.

Beispiel:

1
2
IOLSession session = IOLSession.getSessionForType(SessionType.SZM);
session.getConsent();

Letztes Update: September 6, 2023