Implementierung iOS - Consentfreie Messung
1 Informationen zum Apple Privacy Manifest
Ab dem 01. Mai 2024 ist es notwendig, als Third-Party-SDK Anbieter ein Privacy Manifest mitzuliefern. Zusätzlich zu den Privacy Nutrition Daten, welche seit ca. 2020 bereits angegeben werden müssen, müssen nun noch weitere Angaben getroffen werden.
Ein Privacy Manifest enthält alle Angaben zu Datenschutz-relevanten Themen, welche im Kontext der Veröffentlichung einer App im App Store relevant sind (und dort auch über die Privacy Nutrition Labels deklariert werden) sowie von Apple im Rahmen der App-Einreichung geprüft werden.
Damit die App-Entwickler einen ganzheitlichen Überblick über die Datenschutzinformationen der App inkl. der enthaltenen Frameworks/SDKs/Libraries von Dritten erhalten, sollen neben dem Manifest für die App auch die Manifeste der INFOnline Libraries iOS aufgeführt und eingelesen werden. Entwickler können sich für ihre App via Xcode einen sog. „Privacy Report“ generieren lassen, welcher alle Informationen aus allen Manifesten konsolidiert.
Diese müssen dann im Rahmen der Erstellung bzw. Konfiguration einer App in den App Store Metadaten, Abschnitt „App Datenschutz“, angegeben werden.
Zusätzlich zu den Informationen, welche Daten vom SDK erhoben werden, muss nun auch eine etwaige Nutzung der sog. „Required Reason APIs“ sowie der Grund für die Nutzung deklariert werden.
Darüber hinaus müssten auch die Tracking Domains angegeben werden, sofern die Funktion des SDKs unter „Tracking“ fällt.
1.1 (pseudonym / IOMp) Angaben des Privacy Manifests für die IOLib
Collected Data Types
Identifiers
DeviceID
- used for Tracking
- Purpose: Analytics
Usage Data
Product Interaction
- used for Tracking
- Purpose: Analytics
Advertising Data
- used for Tracking
- Purpose: Analytics
„Required Reason“ APIs (Apple iOS SDK APIs)
Die IOLib iOS nutzt nur eine deklarationspflichtige API zum Zwecke der Verarbeitung der Consent-Informationen gemäß TCF2.0:
API: User defaults APIs
Reason: CA92.1 : Read / write information accessible only by the app
Beispiel des Privacy Reports für die IOMp / pseudonyme Library
Der Privacy Report für die IOLib iOS sieht wie folgt aus:
1.2 (Zensus / IOMb) Angaben des Privacy Manifests für die IOMbLib
Collected Data Types
Identifiers
DeviceID
- used for Tracking
- Purpose: Analytics
Usage Data
Product Interaction
- used for Tracking
- Purpose: Analytics
Advertising Data
- used for Tracking
- Purpose: Analytics
„Required Reason“ APIs (Apple iOS SDK APIs)
Die IOMbLib iOS nutzt keine API dieser Art.
Beispiel des Privacy Reports für die IOMp / zensus Library
Der Privacy Report für die IOMbLib iOS sieht wie folgt aus:
2 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.
Die IOMb-Library muss von der App bei Eintreten des Events explizit aufgerufen werden.
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.
2.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.
Eine PageImpression ist eine Nutzeraktion innerhalb eines mobilen Angebots, die zu einem Aufruf eines Werbemittels führt oder führen könnte. Jede Nutzeraktion darf nur einmal gezählt werden. Nutzeraktionen, die zu keiner potenziellen Werbeauslieferung führen, dürfen nicht gezählt werden.
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:
2.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.
Bei den PI-Events sind die Vorgaben zur PageImpression der ÖWA zu beachten.
- 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“).
3 Bereitstellung/Anforderungen
Im folgenden wird die technische Integration der consentfreien ÖWA-Library in eine iOS Projekt-Struktur beschrieben.
3.1 Bereitstellung
Die IOMb-Library iOS wird als XCFramework bereitgestellt und lässt sich über verschiedene Wege in ein iOS App Projekt integrieren:
- Manuell
- CocoaPods
- Swift Package Manager
Alle Wege der Integration sind gleichwertig und ohne funktionalen Unterschied.
3.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.
4 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
Falls die App keinerlei Swift Code enthält, aber auch mit iOS kleiner 12.2 kompatibel sein soll, sollte die Swift Standard Library im App Bundle enthalten sein. Zu diesem Zweck im Target die Build Settings öffnen und „Always Embed Swift Standard Libraries“ auf YES setzen
4. Xcode: Import des IOMbLibrary Frameworks im ApplicationDelegate und in den ViewControllern
import IOMbLibrary
5 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.
5.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.
5.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
6 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).
6.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.
6.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.
7 Konfiguration, Initialisierung und Nutzung der IOMb-Library iOS
Zur Nutzung der consentfreien ÖWA-Messung muss das Mess-System IOMb AT genutzt werden.
Die dafür notwendigen Parameter wie Angebotskennung und Base URL werden durch INFOnline für jedes Angebot individuell vergeben bzw. im Folgenden erläutert und sind in der nachfolgenden Darstellung nur beispielhaft.
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)
8 IOMb-Library iOS Funktionen
Die IOMb-Library iOS bietet zur Nutzung der IOMb Messung die im Folgenden beschriebenen Funktionen:
8.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)
Die IOMbLib v1.0.x enthält nur das IOMb Mess-System, daher muss kein SessionType als Parameter übergeben werden.
8.2 Konfiguration einer Session
Vor der Initialisierung einer IOMb ÖWA 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:
guard let url = URL(string: "https://data-ef4e2c0163.example.com") else { return }
let configuration = IOMBSessionConfiguration(offerIdentifier: "Angebotskennung", baseURL: url)
8.3 Start einer Session
Die IOMb-Library iOS 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:
IOMBSession.defaultSession(for: .iomb_at).start(with: configuration)
8.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.
8.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 ..
}
}
8.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.
Nur bei Opt-out durch den Nutzer verwenden!
class ViewController: UIViewController {
func disableIOMBSession() {
IOMBSession.defaultSession(for: .iomb_at).terminateSession()
}
}
Soll die Messung fortgeführt werden, muss die IOMb Session neu gestartet werden! Das Vorgehen ist unter „Start einer Session“ beschrieben.
8.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.
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 IOMb-Library wieder gestartet werden. Das Vorgehen ist unter „Start einer Session“ beschrieben.
9 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.
Bitte deaktivieren Sie den Debug-Modus vor der Veröffentlichung der App.
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
Requests und Responses werden im Documents Folder gespeichert. Zu Debugging-Zwecken kann in iTunes Filesharing eingeschaltet und die entsprechenden Dateien einfach kopiert werden.