IOMb - IOMbLib Android API¶

Die IOMbLibrary Android bietet zur Nutzung der IOMb Messung die im Folgenden beschriebenen Funktionen:

Aufruf der IOMb Session¶

Alle im Folgenden beschriebenen Funktionen der IOMb Lib Android müssen auf dem Measurement Objekt aufgerufen werden, auf dem die Session erzeugt wurde.

1
2
3

var IOMBSession : Measurement
IOMBSession = IOMB.createBlocking(setup)
IOMBSession.logEvent(...)

Konfiguration einer Session¶

HINWEIS: Vor der Initialisierung einer IOMb Session muss ein gültiges IOMBSetup Objekt erstellt werden

Parameter:

• Angebotskennung (mandatory)

  Eine eindeutige Kennung des Angebots der jeweiligen App. Die Angebotskennung wird von INFOnline pro App und pro Betriebssystem eindeutig vergeben.

• BaseURL (mandatory)

  Die BaseURL der Serviceplattform ist der eingetragene Domain-Dienstname als CNAME bei Hosting der Serviceplattform der INFOnline. Sollten Sie die Serviceplattform im Self-hosting betreiben, setzen Sie hier Ihren AAA(A) DNS-Eintrag.

• Hybrid Identifier (optional)

  Eine optionale Kennung zur Verknüpfung der Messströme aus dem nativen Teil und Webinhalten in einem WebView innerhalb einer App.

• Customer Data (optional)

  Ein Freifeld für interne Zwecke des Anbieters.

Beispiel:

1
2
3

val setup = IOMBSetup(
            offerIdentifier = "Angebotskennung",
            baseUrl = "https://data-ef4e2c0163.example.com")

Initialisierung einer Session¶

Die IOMb Lib Android muss vor der Erfassung der Events gestartet werden. Dabei müssen die Angebotskennung der App sowie eine gültige BaseURL im IOMb Setup Objekt (s.o.) korrekt gesetzt sein.

Eine Session kann synchron (blocking) oder asynchron (auf einem anderen Thread) erstellt werden

Parameter:

• IOMBSetup (mandatory)

  Für die IOMb-Messung muss ein IOMBSetup Objekt verwendet werden

Beispiel Init Synchron:

1

IOMBSession = IOMB.createBlocking(setup)

Beispiel Init Asynchron:

1
2
3

IOMB.create(setup).subscribe { it ->
    IOMBSession = it
}

Logging eines Events¶

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

1

fun 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.

1
2
3
4

IOLEvent(identifier: String,
         category: String?,
         state: String?,
         comment: String?

Die fehlenden Werte werden dann um nil bzw. Default-Werte ergänzt. Einige der Events werden durch die IOLib automatisch erfasst.

Parameter:

• 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 (mandatory)

  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.

• Kommentar (optional)

  Kommentarfeld. Die Länge dieses Feldes ist nicht beschränkt. Übergabe dieses Wertes ist optional, ist er nicht definiert, soll er nicht übergeben werden.

• Parameter (optional)

  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 state (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
  • IOLGameEventType.NewAchievement
• 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 hier [hier] (Vorgaben_zum_Aufruf.md) beschrieben.

Beispiele:

IOLViewEvent / IOLViewEventType.Appeared

1
2
3
4
5
6
7

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val event = IOLViewEvent(type = IOLViewEvent.IOLViewEventType.Appeared,
                             category = "MainScreen")
    App.IOMB_SESSION.logEvent(event)
}

IOLViewEvent / IOLViewEventTypeRefreshed

1
2
3
4
5
6
7
8

override fun onResume() {
    super.onResume()

    val event = IOLViewEvent(type = IOLViewEvent.IOLViewEventType.Refreshed,
                             category = "MainScreen",
                             comment = "Content refreshed")
    App.IOMB_SESSION.logEvent(event)
}

1
2
3
4
5
6
7
8

override fun onResume() {
    super.onResume()

    val event = IOLAudioEvent(type =    IOLAudioEvent.IOLAudioEventType.Play,
                              category = "Audio",
                              comment = "Audio Playback")
    App.IOMB_SESSION.logEvent(event)
}

Session beenden¶

Die aktive Session der IOMb Lib kann explizit beendet werden. Dies ermöglicht z.B. die Realisierung eines Opt-out während der App-Laufzeit. Etwaige bis dahin erfassten Daten werden nicht mehr versendet.

1

IOMB.delete(Measurement.Type.IOMB)