Skip to content

Commit d8ac334

Browse files
forstisabellaforstisabella
authored
Merge pull request #5013 from segmentio/consent-management-private-beta
Consent management private beta
2 parents 6cd2acd + c364cf1 commit d8ac334

File tree

5 files changed

+303
-1
lines changed

5 files changed

+303
-1
lines changed

‎src/connections/delivery-overview.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ The pipeline view shows the following steps:
2323
- **Successfully received**: Events that Segment ingested from your source
2424
- **Failed on ingest**: Events that Segment received, but were dropped due to internal data validation rules
2525
- **Filtered at source**: Events that were discarded due to schema settings or [Protocols](/docs/protocols/) tracking plans
26-
- **Filtered at destination**: Events that were discarded due to [Destination Filters](/docs/guides/filtering-data/#destination-filters), [filtering in the Integrations object](/docs/guides/filtering-data/#filtering-with-the-integrations-object), or [per source schema integration filters](/docs/guides/filtering-data/#per-source-schema-integrations-filters). Actions destinations also have a filtering capability: for example, if your action is set to only send Identify events, all other event types will be filtered out.
26+
- **Filtered at destination**: Events that were discarded due to [Destination Filters](/docs/guides/filtering-data/#destination-filters), [filtering in the Integrations object](/docs/guides/filtering-data/#filtering-with-the-integrations-object), or [per source schema integration filters](/docs/guides/filtering-data/#per-source-schema-integrations-filters). Actions destinations also have a filtering capability: for example, if your action is set to only send Identify events, all other event types will be filtered out. <!--- Beta users of [Consent Management](/docs/privacy/consent-management/) also see events discarded due to consent preferences.--->
2727
- **Failed delivery**: Events that have been discarded due to errors or unmet destination requirements
2828
- **Successful delivery**: Events that were successfully delivered to the destination
2929

‎src/privacy/configure-consent-management.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: Configure Consent Management
3+
hidden: true
4+
---
5+
> info "Consent Management is in private beta"
6+
> This means that Consent Management features are in active development, and some functionality may change before it becomes generally available. [Contact Segment](https://segment.com/help/contact/){:target="_blank"} with any feedback or questions.
7+
8+
After setting up a third-party consent management platform (CMP), you can enforce the consent collected from your users by configuring consent categories in your your Segment workspace and adding the [consent object](/docs/privacy/consent-management/#consent-object) to your web libraries.
9+
10+
Once you've configured consent in the Segment app, your events are routed only to the categories your end users consented to share data with.
11+
12+
## Prerequisites
13+
14+
> info "Consent management edit and update capabilities limited to Workspace Owners"
15+
> Only users with the Workspace Owner role are able to create, edit, and disable consent categories. All other users have read-only access to Consent Management features.
16+
17+
Before you can configure consent in Segment, take the following steps:
18+
- **Set up your third-party consent management tool and create consent categories**. Take note of your consent categories and the key or ID associated with each category.
19+
- **Know how your company uses each destination**. You need to know which destinations to map to each category.
20+
- **Access to your web libraries**. After you set up consent categories in the Segment app, you need to add a wrapper to your Analytics.js snippet so that Segment can receive your end users' preferences. Segment provides a [wrapper for OneTrust](#step-2-add-the-consent-wrapper-to-analyticsjs), or if you're using a different CMP, you can create your own wrapper using the [instructions provided in the analytics-next repository](https://github.com/segmentio/analytics-next/tree/master/packages/consent/consent-tools){:target="_blank”}.
21+
22+
## Step 1: Create consent categories in the Segment app
23+
24+
> info "Limited availability of sources and destinations during private beta"
25+
> During private beta, you can send events from web sources to consent categories. Enforcement of consent preferences is only available for event streaming destinations, webhooks, and functions. You can map one event streaming destination, webhook, or function to multiple consent categories. All other source and destination types are not impacted by consent mappings.
26+
>
27+
> Storage, RETL, and Engage destinations do not enforce consent preferences.
28+
29+
1. From the [Segment homepage](https://app.segment.com/goto-my-workspace/){:target="_blank”}, select the Privacy tab and click **Consent Management**.
30+
2. On the Consent management page, click **Create categories**.
31+
3. Confirm that you have completed the required prerequisites, and click **Next**.
32+
4. On the Create consent categories page, add the following information to the category form:
33+
- **Category name**: Enter a name that describes your use case for the data sent to this destination. This field only accepts category names that are 20 characters or less.
34+
- **Category ID**: In OneTrust, this is a string of up to five alphanumeric characters, but other CMPs may have a different format. This field is case sensitive.
35+
- **Mapped destinations**: Select one or more of your destinations to map to this category. Category mappings apply to all instances of a destination.
36+
<br/><br/>**Optional**: Click **Add category** to create another category.
37+
5. Once you've finished setting up your category or categories, click **Save**.
38+
39+
> warning "Segment recommends mapping all destinations to a category"
40+
> Segment assumes all destinations without a mapping do not require user consent and will receive all events containing a consent object.
41+
42+
## Step 2: Add the consent wrapper to Analytics.js
43+
44+
If you're using OneTrust as your CMP, you can install the OneTrust integration consent wrapper (`@segment/analytics-wrapper-onetrust`) using a [snippet](#onetrust-for-snippet-users-windowanalytics) or [npm](#onetrust-for-npm-library-users).
45+
46+
If you have a CMP other than OneTrust, you can install the `@segment/analytics-consent-tools` package using the [instructions in the analytics-next repository](https://github.com/segmentio/analytics-next/tree/master/packages/consent/consent-tools){:target="_blank”}.
47+
48+
> error "After adding the consent object to your events, your data is immediately impacted"
49+
> If you disable a consent category, end user consent preferences for that category will not be enforced.
50+
>
51+
> If a destination is mapped to more than one other consent category, and an end user's consent preferences is "false" for either category, data will not get sent.
52+
>
53+
> If an event includes both an integrations object and a consent object, Segment will look at the consent object first, and then take into account the integrations object.
54+
55+
### OneTrust for snippet users (window.analytics)
56+
Delete the `analytics.load()` line from the snippet in the header of your website:
57+
58+
```diff
59+
- analytics.load("<MY_WRITE_KEY>");
60+
```
61+
62+
Run the following initialization code in your project, replacing `<MY_WRITE_KEY>` with your write key:<sup>1</sup>
63+
```ts
64+
import { oneTrust } from '@segment/analytics-consent-wrapper-onetrust'
65+
66+
67+
// snippet users
68+
oneTrust(window.analytics)
69+
window.analytics.load('<WRITE_KEY>')
70+
```
71+
72+
### OneTrust for npm library users
73+
74+
Initialize the OneTrust wrapper by running the following code on your command line, replacing `<MY_WRITE_KEY>` with your write key:<sup>1</sup>
75+
76+
```ts
77+
import { oneTrust } from '@segment/analytics-consent-wrapper-onetrust'
78+
import { AnalyticsBrowser } from '@segment/analytics-next'
79+
80+
export const analytics = new AnalyticsBrowser()
81+
82+
oneTrust(analytics)
83+
84+
analytics.load({ writeKey: '<MY_WRITE_KEY'> })
85+
```
86+
87+
<sup>1</sup>: You can find your write key by navigating to Connections > Sources > [Source Name] > Settings.
88+
89+
## Edit consent categories
90+
91+
If you need to make changes to your consent categories, you can edit them on the Consent Management page. You may experience some latency between making the changes and having the changes take effect.
92+
93+
1. From the [Segment homepage](https://app.segment.com/goto-my-workspace/){:target="_blank”}, select the Privacy tab and click **Consent Management**.
94+
2. On the Consent Management page, navigate to the consent category you'd like to edit and click **Edit**.
95+
3. On the Edit consent category page, you can make changes to the consent category name, ID, and the destinations connected to a category.
96+
4. When you've made your changes, click **Save**.
97+
98+
## Disable consent categories
99+
100+
Disabling a consent category means that Segment no longer enforces end user consent preferences for the destinations in the disabled category. Other consent categories aren't affected.
101+
102+
1. From the [Segment homepage](https://app.segment.com/goto-my-workspace/){:target="_blank”}, select the Privacy tab and click **Consent Management**.
103+
2. On the Consent Management page, disable the toggle for the category you'd like to disable.
104+
3. On the "Disable [category-name]?" popup, enter the category name in the Consent category name field and click **Disable category**.

‎src/privacy/consent-management.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Consent Management Overview
3+
hidden: true
4+
related:
5+
- "/privacy/account-deletion/"
6+
- "/privacy/complying-with-the-gdpr/"
7+
---
8+
> info "Consent Management is in private beta"
9+
> This means that Consent Management features are in active development, and some functionality may change before it becomes generally available. [Contact Segment](https://segment.com/help/contact/){:target="_blank"} with any feedback or questions.
10+
11+
When an end user visits your site, they set **consent preferences**, or make decisions about the types of data they want you to collect, use, and share. These consent preferences are typically presented as a set list of categories that describe how your company intends to use that data. Common categories include personalization, advertising, and site performance.
12+
13+
Segment works with your third-party consent management platform (CMP) or bespoke consent solution to capture an end user's consent preferences and enforce those preferences by only routing events to the categories consented to by an end user.
14+
15+
![Diagram outlining information flowing from an end user to Segment destinations](/docs/privacy/images/consent-overview.png)
16+
17+
After a user sets their consent preferences, Segment captures them with the [Analytics.js Consent Tools wrapper](https://github.com/segmentio/analytics-next/tree/master/packages/consent/consent-tools) and updates the [consent object](#consent-object). The events are then sent downstream to any streaming destinations in categories that a user consented to share data with.
18+
19+
> info ""
20+
> Segment collects consent for both registered users and anonymous users.
21+
22+
## Enforce consent
23+
Segment routes events with a consent object to the destinations in categories consented to by a user and to destinations that do not have a consent category.
24+
25+
If an end user changes the categories they consent to (or if they consent using a different device or identifier,) any events they generate after updating their consent preferences will contain the updated consent information. Segment only sends events to the destinations in the categories that are currently consented to.
26+
27+
> warning "Segment recommends mapping all destinations to a category"
28+
> Segment assumes any destinations without a mapping do not require user consent and will receive all events containing a consent object.
29+
30+
31+
<!--- out of scope for Q2: For example, if a user agreed to share their information with you for all categories on their first visit to your site, and then on their next visit to the site only consented to sharing data for functional and advertising purposes but not for analytics or data sharing, a [Track call](/docs/connections/spec/track/) demonstrating their new consent preferences would have the following format:
32+
33+
``` json
34+
{
35+
"anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895",
36+
"type": "track",
37+
"event": "Segment Consent Preference",
38+
"userId": "u123",
39+
"traits": {
40+
"email": "[email protected]",
41+
"phone": "555-555-5555",
42+
}
43+
"timestamp": "2023-01-01T00:00:00.000Z",
44+
"context": {
45+
"consent": {
46+
"consentPreferences" : {
47+
"Advertising": true,
48+
"Analytics": false,
49+
"Functional": true,
50+
"DataSharing": false
51+
}
52+
}
53+
}
54+
}
55+
```
56+
57+
> info "Segment Consent Preference is a reserved event name"
58+
> Segment has standardized a series of reserved event names that have special semantic meaning and maps these events to tools that support them.
59+
>
60+
> See the [Semantic Events](/docs/connections/spec/semantic/) docs for more details.
61+
62+
--->
63+
64+
To learn more about configuring consent categories in your workspace, see the [Configure Consent Management documentation](/docs/privacy/configure-consent-management/).
65+
66+
## Consent object
67+
68+
Segment requires every event from all of your sources to include the end-user consent preferences, captured by your consent management tools or your application logic, in the form of the **consent object**. The consent object is a JSON object with the following format:
69+
70+
```json
71+
{
72+
"context": {
73+
"consent": {
74+
"consentPreferences": {
75+
"Advertising": true,
76+
"Analytics": false,
77+
"Functional": true,
78+
"DataSharing": false
79+
}
80+
}
81+
}
82+
}
83+
84+
```
85+
<!--- Q3 scope:
86+
87+
### Consent policy version
88+
89+
add to snippet above:" "version": 1,"
90+
91+
Segment assigns a `version` to your consent object. The `version` describes the version of Segment's consent schema that message used.
92+
93+
A consent conflict flag and the categories consented to by a user are both pulled from the consent object and are visible as traits on a user's profile in Unify. --->
94+
95+
96+
## Reconcile consent conflicts
97+
98+
Segment resolves conflicts between your [consent object and your integration object](#reconcile-consent-object-and-integrations-object-conflicts) and between your [CMP and the consent categories you configured in the Segment app](#reconcile-cmp-and-segment-consent-category-conflicts).
99+
100+
### Reconcile consent object and integrations object conflicts
101+
102+
You can add both the integrations object and the consent object to your Segment payloads for greater control over how Segment routes data to your downstream destinations.
103+
104+
> success " "
105+
> For more information about the Integrations object, please see [Filtering your Segment Data](/docs/guides/filtering-data/#filtering-with-the-integrations-object).
106+
107+
If an event includes both an integrations and consent object, Segment will look at the consent object first, and then take into account the integrations object according to the following table:
108+
109+
| Consent Object | Integration Object | Result |
110+
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------ |
111+
| Not provided <br><br> `"context": {` <br>`}` | Not provided or empty object | Data flows to all destinations |
112+
| Empty consent object <br><br> `"context": {`<br>` "consent": {`<br>` }`<br>`}` <br> OR <br> `"context": {`<br>` "consent": {`<br>` "categoryPreference": {` <br>` }`<br>` }` <br> `}`| Not provided or empty object | Data does **NOT** flow to any mapped destinations - consent is considered to be `false` for all categories. <br> <br> Data flows to all destinations **NOT** mapped to a consent category. |
113+
| Not provided <br><br> `"context": {` <br>`}` | `{facebook: true,`<br>`amplitude: false}` | Data flows to the destinations that are `true` in the integrations object (Facebook). Any metadata provided in the integrations object also flows to your downstream destinations. |
114+
| Empty consent object <br><br> `"context": {`<br>` "consent": {`<br>` }`<br>`}` <br> OR <br> `"context": {`<br>` "consent": {`<br>` "categoryPreference": {` <br>` }`<br>` }` <br> `}`| `{facebook: true,`<br>`amplitude: false}` | Data does **NOT** flow to any mapped destinations - consent is considered to be `false` for all categories. <br><br> Data flows to all destinations **NOT** mapped to a consent category, destinations set to `true` in the integrations object, and destinations not included in the integrations object. |
115+
| `{ad: true,` <br>`analytics: false}`<br> <br>_Segment has no category-to-destination mapping for ad and analytics_ | Provided, not provided, or empty object | Data flows to all destinations, as all destinations are unmapped. If the integrations object is present, data flow may be impacted. |
116+
| `{ad: true,` <br>`analytics: false}`<br> <br>_ad = facebook, google-ads_ <br> | Not provided or empty object | Data flows to destinations that map to a consented purpose. In this case, data flows to all ad destinations (Facebook and Google Ads).<br><br> No data flows to analytics destinations. |
117+
| `{ad: true,` <br>`analytics: false}`<br><br>_ad = facebook, google-ads_ <br> _analytics = amplitude_ | `{facebook: true,`<br>`amplitude: false}` | Data flows to all ad destinations, even though Google Ads is not present in the integrations object.<br><br> Data does **NOT** flow to analytics destinations. |
118+
| `{ad: true,` <br>`analytics: false}`<br><br>_ad = facebook, google-ads_ <br> _analytics = amplitude_ | `{facebook: false,`<br>`amplitude: false}` | Data only flows to Google Ads and not to Facebook, which is `false` in the integrations object. <br><br> Data does **NOT** flow to analytics destinations. |
119+
| `{ad: true,` <br>`analytics: false}`<br><br>_ad = facebook, google-ads_ <br> _analytics = facebook, amplitude_ | `{facebook: true,`<br>`amplitude: false}` | When destinations are mapped to multiple categories, data only flows if consent is `true` for all categories. In this case, data only flows to Google Ads and not to Facebook. <br><br>Data does **NOT** flow to analytics destinations. |
120+
| `{ad: true,` <br>`analytics: true}`<br><br>_ad = facebook, google-ads_ <br> _analytics = facebook, amplitude_ | `{facebook: true,`<br>`amplitude: false}` | When destinations are mapped to multiple categories, data only flows if consent is `true` for all categories. In this case, data flows to Google Ads and Facebook. No data flows to Amplitude because it is `false` in the integrations object. |
121+
| `{ad: false,` <br>`analytics: true}` <br><br>_ad = facebook, google-ads_ <br> _analytics = facebook, amplitude_ | `{facebook: true,`<br>`amplitude: false}` | When destinations are mapped to multiple categories, data only flows if consent is `true` for all categories. <br><br>In this example, data does **NOT** flow to any destination because of the interaction between the integrations and consent objects. |
122+
123+
### Reconcile CMP and Segment consent category conflicts
124+
125+
If you have a category configured in your consent management tool (for example, `advertising`) and there is no category with the same ID in Segment, the data will flow to unmapped destinations. If destinations are mapped to a different category in the Segment app, data flow will honor end user consent for that category.
126+
127+
If there is a category configured in Segment (`functional`) that is not mapped in your CMP, data will not flow to destinations mapped to the `functional` category.
128+
129+
## Consent observability
130+
131+
<!--- You can view consent preference events in your [Tracking Plan](/docs/protocols/tracking-plan/create/) and view discarded events in [Delivery Overview](/docs/connections/delivery-overview/). --->
132+
<!---### Tracking Plan
133+
### Delivery Overview
134+
out of current scope--->
135+
Events discarded due to consent preferences appear in [Delivery Overview](/docs/connections/delivery-overview/) at the "Filtered at destination" step with the discard reason __Filtered by end user consent__.

‎src/privacy/images/consent-overview.png

3.01 MB
Loading

0 commit comments

Comments
 (0)