Skip to content

Commit bf971f0

Browse files
forstisabellaforstisabella
committed
editing pass, adding npm/snippet instructions
1 parent 0334242 commit bf971f0

File tree

2 files changed

+149
-43
lines changed

2 files changed

+149
-43
lines changed

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

Lines changed: 115 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -3,45 +3,138 @@ title: Configure Consent Management
33
---
44
> info "Consent Management is currently in private beta"
55
> This means that the 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.
6-
>
7-
> During the private beta, Consent Management only supports website sources and event streaming destinations. All other sources and destinations are not impacted.
86
9-
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. After you've configured consent in the Segment app, your events will be routed only to those streaming destinations consented to by your users.
10-
11-
<!--- note to include: how to find your category ID in tools other than onetrust-->
12-
<!--- Folks need to do some prereq setup, there are two docs - read through and setup ourselves before including information -->
7+
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. After you've configured consent in the Segment app, your events are routed only to destinations consented to by your users.
138

149
## Prerequisites
1510

1611
Before you can configure consent in Segment, take the following steps:
17-
- **Access your consent management tool and set up consent categories**. You need a list of your consent categories and the key or ID associated with each topic.
18-
- **Know how your company maps each destination**. You need to know which destinations map to which categories.
19-
- **Update your web libraries with the consent object**. You need access to your web libraries so you can include the consent object in every event.
12+
- **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 topic.
13+
- **Know how your company uses each destination**. You need to know which destinations to map to each category.
14+
- **A way to update your web libraries with the consent object**. After you set up consent categories in the Segment app, you need to add the Analytics.js snippet to your web libraries so that Segment can receive your end users' preferences.
2015

21-
## Step 1: Create consent categories
16+
## Step 1: Add the analytics-consent-tools package to Analytics.js
2217

23-
<!-- Add note that category ID is case sensitive--->
18+
Before you can create consent categories in the Segment app, you must add the consent tools to your Analytics.js library. For more information about Analytics.js, see the [Analytics.js documentation](/docs/connections/sources/catalog/libraries/website/javascript/).
2419

25-
1. From the [Segment homepage](https://app.segment.com/goto-my-workspace/){:target="_blank”}, select the Privacy tab and click **Consent Management**.
26-
2. On the Consent management page, click **Get started**.
27-
3.
20+
Install the `analytics-consent-tools` using either a [snippet](#snippet-users) or [npm](#npm-library-users).
21+
22+
### Snippet users (window.analytics)
23+
24+
To install the package, run the following code in your project:
25+
26+
```ts
27+
// wrapper.js
28+
import { createWrapper, resolveWhen } from '@segment/analytics-consent-tools'
29+
30+
export const withCMP = createWrapper({
31+
shouldLoad: (ctx) => {
32+
await resolveWhen(() =>
33+
window.CMP !== undefined && !window.CMP.popUpVisible(), 500)
34+
35+
if (noConsentNeeded) {
36+
ctx.abort({ loadSegmentNormally: true })
37+
} else if (allTrackingDisabled) {
38+
ctx.abort({ loadSegmentNormally: false })
39+
}
40+
},
41+
getCategories: () => {
42+
// e.g. { Advertising: true, Functional: false }
43+
return normalizeCategories(window.CMP.consentedCategories())
44+
}
45+
})
46+
```
47+
48+
### npm library users
49+
50+
To install the package using npm, run the following code in your project:
51+
52+
```ts
53+
import { withCMP } from './wrapper'
54+
import { AnalyticsBrowser } from '@segment/analytics-next'
55+
56+
export const analytics = new AnalyticsBrowser()
57+
58+
withCmp(analytics)
59+
60+
analytics.load({
61+
writeKey: '<MY_WRITE_KEY'>
62+
})
63+
```
64+
65+
### Install the OneTrust consent wrapper
66+
67+
If you're using OneTrust, you can install the OneTrust consent wrapper using a [snippet](#for-snippet-users-windowanalytics) or [npm](#for-npm-library-users).
68+
69+
#### For snippet users (window.analytics)
70+
Use the following initialization code:
71+
```ts
72+
import { oneTrust } from '@segment/analytics-consent-wrapper-onetrust'
73+
74+
75+
// snippet users
76+
oneTrust(window.analytics)
77+
window.analytics.load('<WRITE_KEY>')
78+
```
79+
80+
Delete the `analytics.load()` line from the snippet
2881

82+
```diff
83+
- analytics.load("<MY_WRITE_KEY>");
84+
```
2985

30-
## Step 2: Map destinations to consent categories
86+
<!---Ask what the preceding step means in context--->
87+
88+
89+
#### For npm library users
90+
91+
```ts
92+
import { oneTrust } from '@segment/analytics-consent-wrapper-onetrust'
93+
import { AnalyticsBrowser } from '@segment/analytics-next'
94+
95+
export const analytics = new AnalyticsBrowser()
96+
97+
oneTrust(analytics)
98+
99+
analytics.load({ writeKey: '<MY_WRITE_KEY'> })
100+
```
101+
102+
103+
## Step 2: Create consent categories in the Segment app
104+
105+
> info "Limited availability of sources and destinations during private beta"
106+
> During the 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. All other sources and destinations are not impacted by consent mappings.
107+
108+
1. From the [Segment homepage](https://app.segment.com/goto-my-workspace/){:target="_blank”}, select the Privacy tab and click **Consent Management**.
109+
2. On the Consent management page, click **Create categories**.
110+
3. Confirm that you have completed the required prerequisites, and click **Next**.
111+
4. On the Create consent categories page, add the following information to the category form:
112+
- **Category name**: Enter a name that describes your use case for the data sent to this destination
113+
- **Category ID**: In OneTrust, this is a string of up to five alphanumeric characters. Other CMPs may have a different format. This field is case sensitive.
114+
- **Mapped destinations**: Select one or more of your destinations to map to this category.
115+
<br/><br/>**Optional**: Click **Add category** to create another category. You can map one destination to multiple categories.
116+
5. Once you have finished setting up your category or categories, click **Save**.
31117

32-
<br/>
33118
> warning "Segment recommends mapping all destinations to a category"
34-
> Any destination that doesn't have a mapping won't receive events with a consent object.
119+
> For more fine-grained control of your end user consent, Segment recommends that you map all destinations to a consent category.
120+
>
121+
> Any destinations without a mapping will receive all events containing a consent object.
35122
36123

37124
## Step 3: Add the consent object to your web libraries
38125

39-
40126
> error "After adding the consent object to your events, your data is immediately impacted"
41127
> If you disable a consent category, events are not sent to mapped destinations.
42128
>
43-
> If a destination is mapped to multiple categories, and the end user has conflicting preferences, data will be sent to the destination.
44-
>
45-
> If Segment receives an API call with both an integrations object and a consent object, the consent object takes preference.
129+
> If a destination is mapped to multiple categories and the end user has conflicting preferences, data will not be sent to the destination.
46130
47-
## Ingesting consent data
131+
1.
132+
133+
## Editing consent categories
134+
135+
If you need to make changes to your consent categories, you can edit them on the Consent Management page.
136+
137+
1. From the [Segment homepage](https://app.segment.com/goto-my-workspace/){:target="_blank”}, select the Privacy tab and click **Consent Management**.
138+
2. On the Consent Management page, navigate to the consent category you'd like to edit and click **Edit**.
139+
3. On the Edit consent category page, you can make changes to the consent category name, ID, and the destinations connected to a category.
140+
4. When you have made your changes, click **Save**.

‎src/privacy/consent-management.md

Lines changed: 34 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -7,30 +7,26 @@ related:
77
> info "Consent Management is currently in private beta"
88
> This means that the 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.
99
10-
Segment works with your third-party consent management platform (CMP) to capture the categories consented to by an end user and route events to the streaming destinations in the categories consented to by a user.
11-
12-
![Diagram outlining information flowing from an end user to Segment destinations](/docs/privacy/images/consent-overview.png)
13-
1410
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.
1511

16-
Segment captures and then enforces an end user's consent preferences. To collect your users' preferences, you must use a third-party CMP like OneTrust.
12+
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 routing events to the categories consented to by an end user.
13+
14+
![Diagram outlining information flowing from an end user to Segment destinations](/docs/privacy/images/consent-overview.png)
1715

18-
After a user sets their consent preferences, Segment updates the [consent object](#consent-object) with that information. The events are then sent downstream to any streaming destinations in categories that a user consented to share data with.
16+
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.
1917

2018
> success ""
2119
> Segment collects consent for both registered users and anonymous users.
2220
23-
If a user changes the categories they consent to or if they consent using a different device or identifier, any new events will contain the updated consent information.
24-
25-
<!--- rewrite above sentence. Also need to note that they need to make these changes available to Segment, new events are generated that will send updated consent--->
21+
If a 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.
2622

27-
For example:
23+
For example, if a user agreed to share their information with you 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:
2824

2925
``` json
3026
{
3127
"anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895",
3228
"type": "track",
33-
"event": "Consent Change",
29+
"event": "Segment Consent Preference",
3430
"userId": "u123",
3531
"traits": {
3632
"email": "[email protected]",
@@ -39,7 +35,7 @@ For example:
3935
"timestamp": "2023-01-01T00:00:00.000Z",
4036
"context": {
4137
"consent": {
42-
"categoryPreferences" : {
38+
"consentPreferences" : {
4339
"Advertising": true,
4440
"Analytics": false,
4541
"Functional": true,
@@ -50,21 +46,18 @@ For example:
5046
}
5147
```
5248

53-
<!--- UNHIDE DURING PUBLIC BETA: Segment sends the information about their consent, using a [Track call](/docs/connections/spec/track), to your downstream destinations and storage destinations.
54-
55-
This will be added to the profile and used in Engage for auditing purposes. Every message is stamped with preferences.
56-
57-
If a **consent conflict** exists (for example, one user on two different devices consented to two different categories), Segment resolves the conflict according to the [Reconcile Consent]() documentation. --->
58-
59-
Consent information and a consent conflict flag are visible as traits on a user's profile in Unify.
49+
> info "Segment Consent Preference is a reserved event name"
50+
> Segment has standardized a series of reserved event names that have special semantic meaning and maps these events to tools that support them.
51+
>
52+
> See the [Semantic Events](/docs/connections/spec/semantic/) docs for more details.
6053
6154
## Consent object
6255

6356
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:
6457

6558
```json
6659
{
67-
"categoryPreferences" : {
60+
"consentPreferences" : {
6861
"Advertising": true,
6962
"Analytics": false,
7063
"Functional": true,
@@ -74,4 +67,24 @@ Segment requires every event from all of your sources to include the end-user co
7467

7568
```
7669

77-
To learn more about configuring consent management in your workspace, see the [Configure Consent Management docs](/docs/src/privacy/configure-consent-management).
70+
The consent information and a consent conflict flag are visible as traits on a user's profile in Unify.
71+
72+
### Reconcile consent object and integrations object conflicts
73+
74+
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.
75+
76+
> success " "
77+
> For more information about the Integrations object, please see [Filtering your Segment Data](/docs/guides/filtering-data/#filtering-with-the-integrations-object).
78+
79+
If the consent object and integrations object have conflicting destination information, Segment routes data according to the following table:
80+
81+
| Consent Object | Integration Object | Result |
82+
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------ |
83+
| Not provided or empty object | Not provided or empty object | Message delivered to all enabled destinations |
84+
| Not provided or empty object | `{facebook: true,`<br>`amplitude: false}` | Message and metadata delivered to Facebook |
85+
| `{ad: true,` <br>`analytics: false}`<br> <br>//ad = facebook, google ads | Not provided or empty object | Message delivered to the destinations mapped to the consented category. In this case, the message would be delivered to the Ad category (Facebook and Google Ads). No data is delivered to destinations mapped to the analytics category. |
86+
| `{ad: true,` <br>`analytics: false}`<br> <br>//ad = facebook, google ads | `{facebook: true,`<br>`amplitude: false}` | Message delivered to all ad destinations even though google-ads is not provided in the integrations object. Use metadata if provided for Facebook (the current behavior). No data is delivered to analytics destinations. |
87+
| `{ad: true,` <br>`analytics: false}`<br> <br>//ad = facebook, google ads | `{facebook: false,`<br>`amplitude: false}` | Message delivered to all ad destinations (Google Ads) but NOT to Facebook. <br> No data delivered to analytics destinations |
88+
| `{ad: true,` <br>`analytics: false}`<br> <br>//ad = facebook, google ads<br> //analytics = facebook, snowflake | `{facebook: false,`<br>`amplitude: false}` | Message delivered to all ad destinations (even though Facebook belongs to analytics and user is not consenting to analytics.) Use metadata if provided for Facebook (current behavior)<br>No data delivered to analytics destinations (Snowflake) |
89+
90+
To learn more about configuring consent management categories in your workspace, see the [Configure Consent Management documentation](/docs/src/privacy/configure-consent-management).

0 commit comments

Comments
 (0)