You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add Segment driven consent management support for your application via this plugin for [Analytics-Swift](https://github.com/segmentio/analytics-swift)
4
4
5
-
## Adding the dependency
5
+
This plugin provides the framework to integration Consent Management Platform (CMP) SDKs like OneTrust to supply consent status and potential block events going to device mode destinations.
6
+
7
+
Read more about Segment's Consent Management solutions [here](https://segment.com/docs/privacy/configure-consent-management/), as well as enabling it for your workspace.
8
+
9
+
## Background
10
+
11
+
Consent Management is the management of a user’s consent preferences related to privacy. You might be familiar with the Privacy Pop-ups that have become mandated recently that ask the user if he or she consents to the use of certain category of cookies:
The Privacy pop-up asks the user if he or she will consent to the use of cookies and allows the user to customize their consent by turning on/off different categories of cookies.
17
+
18
+
After the user selects “Allow All” or “Save Preferences” a callback is fired and the owner of the website is notified as to the consent preferences of a given user. The website owner must then store that consent preference and abide by it. Any rejected cookies must not be set or read to avoid large fines that can be handed down by government authorities.
19
+
20
+
Additionally, besides the initial pop-up the app owner must give users a way to later change any preferences they originally selected. This is usually accomplished by providing a button to display the customization screen.
21
+
22
+
23
+
## Segment managed CMP
24
+
25
+
Segment provides a framework for users to integrate any CMP they choose and use the Segment web app to map consent categories to device mode destinations. This information is sent down the analytics-kotlin SDK and stored for later lookup.
26
+
27
+
Every event that flows through the library will be stamped with the current status according to whatever configured CMP is used. Event stamping is handled by the ConsentManagementPlugin.
28
+
29
+
Using consent status stamped on the events and the mappings sent down from the Segment web app each event is evaluated and action is taken. Currently the supported actions are:
30
+
31
+
- Blocking - This action is implemented by the ConsentBlockingPlugin
32
+
33
+
## Event Stamping
34
+
35
+
Event stamping is the process of adding the consent status information to an existing event. The information is added to the context object of every event. Below is a before and after example:
When notified by the CMP SDK that consent has changed, a track event with name “Segment Consent Preference” will be emitted. Below is example of what that event will look like:
![Shows how an event is stamped and later checked for consent](imgs/main-flow-diagram.png?raw=true"Event Flow Diagram")
117
+
118
+
1. An event is dropped onto the timeline by some tracking call.
119
+
2. The ConsentManagementPlugin consumes the event, stamps it, and returns it.
120
+
3. The event is now stamped with consent information from this point forward.
121
+
4. The event is copied. The copy is consumed by a Destination Plugin and continues down its internal timeline. The original event is returned and continues down the main timeline.
122
+
a. The stamped event is now on the timeline of the destination plugin.
123
+
b. The event reaches the ConsentBlockingPlugin which makes a decision as to whether or not to let the event continue down the timeline.
124
+
c. If the event has met the consent requirements it continues down the timeline.
125
+
5. The event continues down the timeline.
126
+
127
+
128
+
129
+
130
+
## Getting Started
6
131
7
132
### via Xcode
8
133
In the Xcode `File` menu, click `Add Packages`. You'll see a dialog where you can search for Swift packages. In the search field, enter the URL to this repo.
@@ -23,42 +148,74 @@ Open your Package.swift file and add the following do your the `dependencies` se
Open the file where you setup and configure the Analytics-Swift library. Add this plugin to the list of imports.
155
+
Or build your own integration (see below)
30
156
31
-
```
32
-
import Segment
33
-
import SegmentConsent // <-- Add this line
34
-
```
35
-
36
-
Just under your Analytics-Swift library setup, call `analytics.add(plugin: ...)` to add an instance of the plugin to the Analytics timeline.
157
+
Next you'll need to write some setup/init code where you have your
158
+
Analytics setup:
37
159
38
-
```
160
+
```swift
39
161
let analytics =Analytics(configuration: Configuration(writeKey: "<YOUR WRITE KEY>")
40
162
.flushAt(3)
41
163
.trackApplicationLifecycleEvents(true))
42
164
43
165
let consentManager =ConsentManager(provider: MyConsentProvider())
44
166
analytics.add(plugin: consentManager)
167
+
// add any device mode destinations you might have ...
168
+
analytics.add(plugin: FirebaseDestination())
169
+
analytics.add(plugin: TaplyticsDestination())
45
170
46
171
// Note: Different consent management providers may require consentManager.start() be called differently.
47
172
// Tell the consent manager to start processing events. It will queue events until start() is called.
48
173
consentManager.start()
49
-
50
174
```
51
175
52
-
Your events will now begin to have the consent management preferences applied.
176
+
The Consent Manager plugin will automatically add a ConsentBlockingPlugin to any device mode destinations, so there's no extra steps for you to do in your code. Blocking for cloud mode destinations will be handled server-side at Segment.
177
+
178
+
## Building your own integration
179
+
180
+
In order to integrate a new CMP all you have down is make your own ConsentCategoryProvider object.
181
+
182
+
### Consent Category Provider
183
+
184
+
You'll need to create a `ConsentCategoryProvider` that will provide a mapping of consent category to whether or not a given category has been consented by the user. It must also provide a way to inform the `ConsentManager` of any changes that happen during runtime.
185
+
186
+
Example:
187
+
```swift
188
+
classMyConsentProvider: ConsentCategoryProvider {
189
+
// this will be set later by the ConsentManager.
190
+
var changeCallback: ConsentChangeCallback?=nil
191
+
// this is the imaginary Consent SDK you supplied/wrote.
192
+
let consentSDK: MyConsentSDK
193
+
194
+
var categories: [String : Bool] {
195
+
// Returns a simple dictionary of categories and their
0 commit comments