Zum Inhalt

IOMb Library iOS Funktionen

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

Aufruf der Default Session

Alle im Folgenden beschriebenen Funktionen der IOLib iOS müssen auf dem Default Session Objekt aufgerufen werden. Die IOMbLib enthält nur das IOMb Mess-System, daher muss kein SessionType als Parameter übergeben werden.

1
let session = IOMBSession.defaultSession

Konfiguration einer Session

Hinweis

Vor dem Start einer IOMb Session muss ein gültiges Konfigurations-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
guard let url = URL(string: "https://data-ef4e2c0163.example.com") else { return }
let configuration = IOMBSessionConfiguration(offerIdentifier: "Angebotskennung", baseURL: url)

Start einer Session

Hinweis

Die IOLib muss vor der Erfassung der Events gestartet werden. Dabei müssen die Angebotskennung der App sowie eine gültige BaseURL in der SessionConfiguration (s.o.) korrekt gesetzt sein.

Parameter:

  • SessionConfiguration (mandatory)

    Ein SessionConfiguration Objekt. Für die IOMb-Messung muss IOMBSessionConfiguration verwendet werden!

Beispiel:

1
IOMBSession.defaultSession.start(with: configuration)

Logging eines Events

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

1
func logEvent(_ event: IOMBEvent)

Um ein Event zu erzeugen, muss ein Initializer der entsprechenden IOMBEvent-Subklasse aufgerufen werden. Dabei können bis zu drei Parameter übergeben werden, zwei davon sind optional (ParameterDictionary ist ein Swift typealias für Dictionary<String, String>).

1
2
3
4
IOMBEvent(type: IOMBEventType,
          category: String?,
          comment: String?,
          parameter: ParameterDictionary?)

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

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 IOMBCustomEvent 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 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 „IOMBEvent“ abgeleitete Event-Klassen mit den zugehörigen Types zur Verfügung:

  • IOMBAdvertisementEvent
    • IOMBAdvertisementEventTypeOpen
    • IOMBAdvertisementEventTypeClose
  • IOMBAudioEvent
    • IOMBAudioEventTypePlay
    • IOMBAudioEventTypePause
    • IOMBAudioEventTypeStop
    • IOMBAudioEventTypeNext
    • IOMBAudioEventTypePrevious
    • IOMBAudioEventTypeReplay
    • IOMBAudioEventTypeSeekBack
    • IOMBAudioEventTypeSeekForward
  • IOMBBackgroundTaskEvent
    • IOMBBackgroundTaskEventTypeStart
    • IOMBBackgroundTaskEventTypeEnd
  • IOMBCustomEvent
    • type entfällt
    • stattdessen name (frei bestimmbarer String, auf 255 Zeichen beschränkt)
  • IOMBDataEvent
    • IOMBDataEventTypeCancelled
    • IOMBDataEventTypeRefresh
    • IOMBDataEventTypeSucceeded
    • IOMBDataEventTypeFailed
  • IOMBDeviceOrientationEvent
    • type entfällt (IOMBDeviceOrientationEventTypeOrientationChanged)
  • IOMBDocumentEvent
    • IOMBDocumentEventTypeOpen
    • IOMBDocumentEventTypeEdit
    • IOMBDocumentEventTypeClose
  • IOMBDownloadEvent
    • IOMBDownloadEventTypeCancelled
    • IOMBDownloadEventTypeStart
    • IOMBDownloadEventTypeSucceeded
    • IOMBDownloadEventTypeFailed
  • IOMBGameEvent
    • IOMBGameEventTypeAction
    • IOMBGameEventTypeStarted
    • IOMBGameEventTypeFinished
    • IOMBGameEventTypeWon
    • IOMBGameEventTypeLost
    • IOMBGameEventTypeNewHighscore
    • IOMBGameEventTypeNewAchievement
  • IOMBGestureEvent
    • type entfällt (IOMBGestureEventTypeShake)
  • IOMBHardwareButtonEvent
    • type entfällt (IOMBHardwareButtonEventTypePushed)
  • IOMBIAPEvent
    • IOMBIAPEventTypeStarted
    • IOMBIAPEventTypeFinished
    • IOMBIAPEventTypeCancelled
  • IOMBLoginEvent
    • IOMBLoginEventTypeSucceeded
    • IOMBLoginEventTypeFailed
    • IOMBLoginEventTypeLogout
  • IOMBOpenAppEvent
    • IOMBOpenAppEventTypeMaps
    • IOMBOpenAppEventTypeOther
  • IOMBPushEvent
    • type entfällt (IOMBPushEventTypeReceived)
  • IOMBUploadEvent
    • IOMBUploadEventTypeCancelled
    • IOMBUploadEventTypeStart
    • IOMBUploadEventTypeSucceeded
    • IOMBUploadEventTypeFailed
  • IOMBVideoEvent
    • IOMBVideoEventTypePlay
    • IOMBVideoEventTypePause
    • IOMBVideoEventTypeStop
    • IOMBVideoEventTypeNext
    • IOMBVideoEventTypePrevious
    • IOMBVideoEventTypeReplay
    • IOMBVideoEventTypeSeekBack
    • IOMBVideoEventTypeSeekForward
  • IOMBViewEvent
    • IOMBViewEventTypeAppeared
    • IOMBViewEventTypeRefreshed
    • IOMBViewEventTypeDisappeared

Weitere Details zu den messbaren Events und der dazugehörigen States sind [hier] (Vorgaben_zum_Aufruf.md) beschrieben.

Beispiele:

  • IOMBViewEvent / IOMBViewEventTypeAppeared
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
class ViewController: UIViewController {

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        let event = IOMBViewEvent(type: .appeared,
                                  category: "Home",
                                  comment: nil)
        IOMBSession.defaultSession.logEvent(event)
        // Other Code ..
   }
}
  • IOMBViewEvent / IOMBViewEventTypeRefreshed
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
class ViewController: UIViewController {

    @IBAction func refresh(sender: AnyObject) {
        let event = IOMBViewEvent(type: .refreshed,
                                  category: "Home",
                                  comment: "Content refreshed")
        IOMBSession.defaultSession.logEvent(event)
        // Other Code ..
    }
}
  • IOMBAudioEvent / IOMBAudioEventTypePlay
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
class ViewController: UIViewController {

    @IBAction func refresh(sender: AnyObject) {
        let event = IOMBAudioEvent(type: .play,
                                   category: "Audio"
                                   comment: "Audio playback")
        IOMBSession.defaultSession.logEvent(event)
        // Other Code ..
    }
}

Session beenden

func 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!

1
2
3
4
5
6
class ViewController: UIViewController {

    func disableIOMBSession() {
        IOMBSession.defaultSession.terminateSession()
    }
}
Hinweis

Soll die Messung fortgeführt werden, muss die IOLib Session neu gestartet werden! Das Vorgehen ist unter Start einer Session beschrieben.

Einbindung Opt-out-Funktion

Den Nutzern einer App muss eine Opt-out Funktion zur Verfügung gestellt werden. Die Implementierung obliegt dem Entwickler der jeweiligen App und sollte bei Aktivierung durch den Benutzer dazu führen, dass die IOLib entweder gar nicht initialisiert wird oder die laufende Session explizit beendet wird. Das Vorgehen ist unter Session beenden beschrieben.

Nach Einbindung der Funktion können die Nutzer der App das Opt-out aktivieren und deaktivieren. Sofern ein Opt-out aktiviert wird, werden keine Messdaten erfasst.

Hinweis

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

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


Letztes Update: February 11, 2022