Implementierung iOS - Consentfreie Messung

1 Vorgaben zum Aufruf der IOMb Library

Die Erfassung der App-Nutzung durch den Benutzer erfolgt, indem die App die IOMb-Library bei definierten Ereignissen, welche eine Nutzer-Interaktion kennzeichnen, aufruft.
Die Nutzer-Interaktion wird als Event bezeichnet.

Weiterhin misst die IOMbLibrary bestimmte System- oder App-spezifische Werte automatisch. Zu diesem Zweck muss die Integration der IOMbLibrary iOS exakt wie im Abschnitt Integration der IOMB Lib iOS beschrieben erfolgen.

1.1 Interpretation von Events als mobile PI

Die nachfolgend aufgeführten Vorgaben definieren, wie die ÖWA- Library im Kontext der IOMb Mobile Applications Messung zu verwenden ist.
Aus technischer Sicht wird zwischen 2 Typen von Events unterschieden:

PI-Events

Bei den PI-Events wird der Event dazu benutzt, analog zur Web-Messung, eine PageImpression zu erzeugen. Diesem Event muss ein Contentpath (in der Folge einfach als „CP“ bezeichnet) zugeordnet werden. Dieser CP kann anschließend den unterschiedlichen Kategorien zugeordnet werden und dient als Grundlage für die Bildung von Belegungseinheiten. Bei den PI-Events sind die Vorgaben zur Page Impression der ÖWA zu beachten.

Voraussetzungen für die Zuweisung einer PI zu einem Angebot:

Der ausgelieferte Inhalt muss (bei mobile enabled Websites) den FQDN bzw. (bei Apps) den App-Namen des Angebots (oder Alias/Redirect) oder den zugewiesenen MEW- oder App-Namen des Angebots tragen.

Nutzeraktion:

Eine PI wird ausgelöst durch eine vom Nutzer durchgeführte Aktion. Darunter fallen ebenfalls: Reload, Öffnen einer App, Öffnen eines Browsers.

Keine Nutzeraktion:

Aufruf eines Inhalts durch eine automatische Weiterleitung (außer Redirects und Alias)., automatischer Reload, das Aufrufen eines Inhaltes beim Schließen (auch: Background) eines Browserfensters oder einer App, das Aufrufen von Inhalten über Robots/Spider und Ähnliches.

Keine PageImpression:

Das Scrollen innerhalb eines bereits geladenen Inhalts.

Non-PI-Events

Non-PI-Events sind Nutzeraktionen, die als Event im consentfreien System erfasst werden, jedoch nicht zur Zählung einer Mobile Impression führen. Diesem Event darf kein Contentpath zugeordnet werden. Beispiele für Non-PI-Events sind

• automatisch von der IOMb-Library erfasste Events
• vom Anbieter festgelegte Events, welche keine mobile PI darstellen und dennoch als Events gemessen werden sollen, um z.B. die Nutzung der App durch die Nutzer besser nachvollziehen zu können.

Richtlinien zur Vergabe der Codes

Bei den PI-Events ist der CP als eindeutige Kennzeichnung des angezeigten Inhalts mitzugeben. Der CP wird vom App-Anbieter spezifiziert.

Bei der Spezifikation des Contentpaths sind die CP-Richtlinien der ÖWA zu beachten:

• Länge: Ein CP darf maximal 255 Zeichen enthalten
• Anzahl: Es dürfen maximal 15.000 CPs verwendet werden
• Erlaubte Zeichen: a-z, A-Z, 0-9; Komma „,“; Bindestrich „-“; Unterstrich „_“; Slash „/“

Eine ausführliche Liste gültiger ÖWA-Kategorien (Contentpath) finden Sie unter:

ÖWA-Kategoriensystem

1.2 Events

In den nachfolgenden Tabellen sind Events aufgeführt, welche in der Messung erhoben werden bzw. erhoben werden können. Unter welchen Umständen ein Event zu einer Page Impression führen kann, wird im Folgenden ebenfalls erläutert.

PI-Events

Im Folgenden sind Events aufgeführt, welche typischerweise zur Auslösung einer PI führen. Die Übernahme des Schemas wird empfohlen. Die Events müssen manuell ausgelöst werden. Das Vorgehen ist im Kapitel „Logging eines Events“ beschrieben. Eine automatische Erhebung erfolgt nicht. PI-Events muss ein Contentpath zugeordnet werden. Dieser Contentpath kann anschließend den unterschiedlichen Kategorien zugeordnet werden und dient als Grundlage für die Bildung von Belegungseinheiten.

• Event Klasse: IOLViewEvent
• Event Type: Appeared
• Event: Ein View (aka „Page“) wurde angezeigt oder mit neuen Daten aktualisiert
• Bemerkung: Beispiele:
  Appeared: initialer Aufruf einer Seite

Sobald in der App ein unter „manuell auszulösende Events“ beschriebenes Ereignis ausgelöst wird, ist die IOMb-Library iOS per logEvent aufzurufen. Hierbei ist eine Instanz der entsprechenden IOLEvent-Subklasse als Parameter zu übergeben (siehe dazu auch „IOMb-Library iOS Funktionen“).

2 Bereitstellung/Anforderungen

Im folgenden wird die technische Integration der consentfreien ÖWA-Library in eine iOS Projekt-Struktur beschrieben.

2.1 Bereitstellung

Die IOMb-Library iOS wird als XCFramework bereitgestellt und lässt sich über verschiedene Wege in ein iOS App Projekt integrieren:

1. Manuell
2. CocoaPods
3. Swift Package Manager

Alle Wege der Integration sind gleichwertig und ohne funktionalen Unterschied.

2.2 Anforderungen

Die IOMbLib iOS unterstützt ausschließlich die Integration über die Entwicklungsumgebung Xcode unter macOS.

Entwicklungsumgebung

• macOS 12.5 (Monterey) und höher
• iOS SDK 164 und höher
• Xcode 14 oder höher
• Objective-C oder Swift

iOS APPs, welche die IOMb Lib iOS benutzen, müssen mind. mit iOS SDK 1654 kompiliert werden.

Deployment Target muss mind. auf iOS 11.0 eingestellt werden.

Betriebssystem/Plattform

Die IOMb-Library iOS unterstützt den Betrieb unter 32-Bit und 64-Bit Architekturen. Die IOMb-Library iOS setzt für den Betrieb iOS 11.0 oder höher voraus.

Kompatibilität

Eine neue Version von Xcode bzw. des iOS-Betriebssystems macht evtl. ein Update der IOMb-Library iOS notwendig. Eine vollständige Aufwärtskompatibilität kann u.U. nicht gewährleistet werden.

3 Manuelle Integration der IOMb-Library iOS

Die manuelle Integration der IOMbLibrary iOS erfolgt in wenigen Schritten:

1. IOMbLibrary.xcframework hier herunterladen.

2. Xcode: IOMbLibrary.xcframework im Tab „General“ des Target per Drag’N’Drop in die Sektion „Frameworks, Libraries, and Embedded Content“ ziehen (Embed & Sign)

3. Xcode: In den Build Settings des Targets die Optionen „Enable Modules (C and Objective-C)“ sowie „Link Framework Automatically“ auf YES setzen

4. Xcode: Import des IOMbLibrary Frameworks im ApplicationDelegate und in den ViewControllern

import IOMbLibrary

4 Integration der IOMb-Library iOS via CocoaPods

Dies ist eine Schritt-für-Schritt-Anleitung für die Installation der consentfreien ÖWA-Library in Ihrem Projekt via CocoaPods.

4.1 Voraussetzungen

• Xcode 13 oder höher. Sie können die letzte stabile Version hier herunterladen.
• CocoaPods 1.10.0 or höher. Sie können die letzte stable Version hier herunterladen.
• Das Minimum Deployment Target in Ihrem Projekt sollte iOS 11.0 sein.

Falls Sie kein Xcode-Projekt haben und die IOMb-Library iOS trotzdem testen möchten, können Sie das Beispielprojekt hier herunterladen.

4.2 Die IOMb-Library CocoaPods Dependency hinzufügen

1. Erstellen Sie ein Podfile, falls Sie noch keins haben, ansonsten gehen Sie weiter zu Schritt 2:

Öffnen Sie Terminal und wechseln Sie zum Verzeichnis, in dem sich Ihr Projekt befindet

cd pfad/zum/projekt

Führen Sie folgenden Befehl aus – dies erstellt ein Podfile in Ihrem Projektverzeichnis

pod init

2. Öffnen Sie das Podfile (mit einem beliebigen Texteditor) und ergänzen Sie die IOMb Lib iOS pod URL:

pod 'IOMbLibrary', :git => 'https://repo.infonline.de/iom/base/sensors/app/ios.git'

3. Ihr Podfile sollte wie folgt aussehen

target 'IhrTargetName' do
use_frameworks!

pod 'IOMbLibrary', :git => 'https://repo.infonline.de/iom/base/sensors/app/ios.git'

end

4. Öffnen Sie Terminal und wechseln Sie zum Verzeichnis, in dem sich Ihr Podfile befindet:

cd pfad/zum/podfile

5. Führen Sie folgenden Befehl aus – dies installiert das pod und erstellt eine .xcworkspace Datei

pod install

6. Öffnen Sie Ihr Projekt in Xcode über die .xcworkspace Datei (statt über .xcodeproj).
7. Fahren Sie fort mit der Konfiguration und Initialisierung der IOMbLibrary: Link

5 Integration der IOMb-Library iOS via Swift Package Manager

Dies ist eine Schritt-für-Schritt-Anleitung für die Installation der IOMb-Library in Ihrem Projekt via Swift Package Manager (SPM).

5.1 Voraussetzungen

• Xcode 14 oder höher. Sie können die letzte stabile Version hier herunterladen.
• Das Minimum Deployment Target in Ihrem Projekt sollte iOS 11.0 sein.

Falls Sie kein Xcode-Projekt haben und die IOMbLibrary trotzdem testen möchten, können Sie das Beispielprojekt hier herunterladen.

5.2 Die IOMb-Library SPM Dependency hinzufügen

1. Öffnen Sie Ihr Projekt in Xcode und wählen Sie Ihr Projekt im Xcode Project Navigator aus.
2. Wählen Sie Ihr Projekt aus der Project und Targets Liste.
3. Wählen Sie den „Package Dependencies“ Tab.
4. Klicken Sie auf das + Symbol, um das Swift Package hinzuzufügen
Alternativ können Sie das Swift Package auch hinzufügen über File > Swift Packages > Add Package Dependency…
5. Kopieren Sie folgende IOMbLibrary Swift Package Repository URL in das Suchfeld. Unter „Dependency Rule“ muss „Up to Next Major Version“ ausgewählt sein.

https://repo.infonline.de/iom/base/sensors/app/ios

6.

7. Klicken Sie auf Finish. Die IOMb-Library sollte nun unter Swift Package Dependencies im Xcode Project Navigator gelistet sein.

8. Fahren Sie mit der Konfiguration und Initialisierung der IOMb-Library iOS fort.

6 Konfiguration, Initialisierung und Nutzung der IOMb-Library iOS

Zur Nutzung der consentfreien ÖWA-Messung muss das Mess-System IOMb AT genutzt werden.

Initialisierung einer IOMb ÖWA Session

Erstellung eines IOMBSessionConfiguration Objekts und Initialisierung der IOMb_AT Session

import IOMbLibrary

...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: 
    [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        startIOMbATSession()
        return true
    }

private func startIOMbATSession() {
    guard let url = URL(string: "https://data-ef4e2c0163.example.com") else { return }
    let configuration = IOMBSessionConfiguration(offerIdentifier: "Angebotskennung", baseURL: url)
v1.1.+: IOMBSession.defaultSession(for: .iomb_at).start(with: configuration) 
v1.0.x: IOMBSession.defaultSession.start(with: configuration) 
}

Angebotskennung und https://data-ef4e2c0163.example.com sind Beispiele, Ihre angebotsindividuellen Werte erhalten Sie von der INFOnline. Falls Sie die Serviceplattform als Self-hosting betreiben, wird im folgenden Kapitel beschrieben, wie die baseUrl aufgebaut ist.

Event Logging

Events können in den View Controllern der App geloggt werden, z.B. der Aufruf eines Views:

let event = IOMBViewEvent(type: .appeared, category: "Home", comment: nil)
 v1.1.+: IOMBSession.defaultSession(for: .iomb).logEvent(event) 
 v1.0.x: IOMBSession.defaultSession.logEvent(event)

 v1.1.+: IOMBSession.defaultSession(for: .iomb_at).logEvent(event) 
v1.0.x: IOMBSession.defaultSession.logEvent(event)

7 IOMb-Library iOS Funktionen

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

7.1 Aufruf der Default Session

Alle im Folgenden beschriebenen Funktionen der IOMb-Library iOS müssen auf dem Default Session Objekt aufgerufen werden.

let session = IOMBSession.defaultSession(for: .iomb_at)

7.2 Konfiguration 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.
• 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:

guard let url = URL(string: "https://data-ef4e2c0163.example.com") else { return }
let configuration = IOMBSessionConfiguration(offerIdentifier: "Angebotskennung", baseURL: url)

7.3 Start einer Session

Parameter:

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

Beispiel:

IOMBSession.defaultSession(for: .iomb_at).start(with: configuration)

7.4 Logging eines Events

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

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

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 IOMb-Library 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 Contentpath wird im Parameter “category“ übermittelt. Dieser Contentpath wird vom Anbieter selbst festgelegt. Der Contentpath dient zur inhaltlichen Kennzeichnung des angezeigten Contents. Der Anbieter entscheidet anhand der im Kapitel 1 (Richtlinien zur Vergabe der Codes) beschriebenen Richtlinien, ob ein Event eine mobile PI im Sinne der ÖWA Richtlinien darstellt. Wenn ein Event unter die Definition einer mobilen PI fällt, ist zwingend ein Contentpath 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)
  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.
  

7.5 Verfügbare Events

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

• IOMBViewEvent
  • IOMBViewEventTypeAppeared

Beispiele:

• IOMBViewEvent / IOMBViewEventTypeAppeared

class ViewController: UIViewController {

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        let event = IOMBViewEvent(type: .appeared,
                                  category: "Home",
                                  comment: nil)
        IOMBSession.defaultSession(for: .iomb_at).logEvent(event)
        // Other Code ..
   }
}

7.6 Session beenden

func terminateSession()

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

class ViewController: UIViewController {

    func disableIOMBSession() {
        IOMBSession.defaultSession(for: .iomb_at).terminateSession()
    }
}

7.7 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 IOMb-Library 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.

8 IOMb-Library iOS - Debug Informationen

Zum Zweck der allgemeinen Fehleranalyse und insb. des Versands der Messdaten kann die IOMb-Library iOS in einen Debug-Modus versetzt werden.
In diesem Debug-Modus erzeugt die IOMb-Library iOS Ausgaben im Logstrom (Konsole).

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: 
    [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    IOMBLogging.setDebugLogLevel(.info)
    return true
}

Art und Umfang der Logausgaben können über einen DebugLevel bestimmt werden.

Folgende Debug-Level sind definiert:

• IOMBDebugLevelOff: Deaktiviert (Default)
• IOMBDebugLevelError: nur Fehler
• IOMBDebugLevelWarning: Fehler und Warnungen
• IOMBDebugLevelInfo: Fehler, Warnungen und Infos
• IOMBDebugLevelTrace: Fehler, Warnungen, Infos, Events, Requests und Responses