diff --git a/src/connections/delivery-overview.md b/src/connections/delivery-overview.md index 52db4bcc67..1ad8f85530 100644 --- a/src/connections/delivery-overview.md +++ b/src/connections/delivery-overview.md @@ -23,7 +23,7 @@ The pipeline view shows the following steps: - **Successfully received**: Events that Segment ingested from your source - **Failed on ingest**: Events that Segment received, but were dropped due to internal data validation rules - **Filtered at source**: Events that were discarded due to schema settings or [Protocols](/docs/protocols/) tracking plans -- **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. +- **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. - **Failed delivery**: Events that have been discarded due to errors or unmet destination requirements - **Successful delivery**: Events that were successfully delivered to the destination diff --git a/src/privacy/configure-consent-management.md b/src/privacy/configure-consent-management.md new file mode 100644 index 0000000000..89ed8add6f --- /dev/null +++ b/src/privacy/configure-consent-management.md @@ -0,0 +1,104 @@ +--- +title: Configure Consent Management +hidden: true +--- +> info "Consent Management is in private beta" +> 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. + +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. + +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. + +## Prerequisites + +> info "Consent management edit and update capabilities limited to Workspace Owners" +> 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. + +Before you can configure consent in Segment, take the following steps: +- **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. +- **Know how your company uses each destination**. You need to know which destinations to map to each category. +- **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”}. + +## Step 1: Create consent categories in the Segment app + +> info "Limited availability of sources and destinations during private beta" +> 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. +> +> Storage, RETL, and Engage destinations do not enforce consent preferences. + +1. From the [Segment homepage](https://app.segment.com/goto-my-workspace/){:target="_blank”}, select the Privacy tab and click **Consent Management**. +2. On the Consent management page, click **Create categories**. +3. Confirm that you have completed the required prerequisites, and click **Next**. +4. On the Create consent categories page, add the following information to the category form: + - **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. + - **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. + - **Mapped destinations**: Select one or more of your destinations to map to this category. Category mappings apply to all instances of a destination. +

**Optional**: Click **Add category** to create another category. +5. Once you've finished setting up your category or categories, click **Save**. + +> warning "Segment recommends mapping all destinations to a category" +> Segment assumes all destinations without a mapping do not require user consent and will receive all events containing a consent object. + +## Step 2: Add the consent wrapper to Analytics.js + +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). + +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”}. + +> error "After adding the consent object to your events, your data is immediately impacted" +> If you disable a consent category, end user consent preferences for that category will not be enforced. +> +> 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. +> +> 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. + +### OneTrust for snippet users (window.analytics) +Delete the `analytics.load()` line from the snippet in the header of your website: + +```diff +- analytics.load(""); +``` + +Run the following initialization code in your project, replacing `` with your write key:1 +```ts +import { oneTrust } from '@segment/analytics-consent-wrapper-onetrust' + + +// snippet users +oneTrust(window.analytics) +window.analytics.load('') +``` + +### OneTrust for npm library users + +Initialize the OneTrust wrapper by running the following code on your command line, replacing `` with your write key:1 + +```ts +import { oneTrust } from '@segment/analytics-consent-wrapper-onetrust' +import { AnalyticsBrowser } from '@segment/analytics-next' + +export const analytics = new AnalyticsBrowser() + +oneTrust(analytics) + +analytics.load({ writeKey: ' }) +``` + +1: You can find your write key by navigating to Connections > Sources > [Source Name] > Settings. + +## Edit consent categories + +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. + +1. From the [Segment homepage](https://app.segment.com/goto-my-workspace/){:target="_blank”}, select the Privacy tab and click **Consent Management**. +2. On the Consent Management page, navigate to the consent category you'd like to edit and click **Edit**. +3. On the Edit consent category page, you can make changes to the consent category name, ID, and the destinations connected to a category. +4. When you've made your changes, click **Save**. + +## Disable consent categories + +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. + +1. From the [Segment homepage](https://app.segment.com/goto-my-workspace/){:target="_blank”}, select the Privacy tab and click **Consent Management**. +2. On the Consent Management page, disable the toggle for the category you'd like to disable. +3. On the "Disable [category-name]?" popup, enter the category name in the Consent category name field and click **Disable category**. diff --git a/src/privacy/consent-management.md b/src/privacy/consent-management.md new file mode 100644 index 0000000000..a6018a98c1 --- /dev/null +++ b/src/privacy/consent-management.md @@ -0,0 +1,135 @@ +--- +title: Consent Management Overview +hidden: true +related: + - "/privacy/account-deletion/" + - "/privacy/complying-with-the-gdpr/" +--- +> info "Consent Management is in private beta" +> 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. + +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. + +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. + +![Diagram outlining information flowing from an end user to Segment destinations](/docs/privacy/images/consent-overview.png) + +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. + +> info "" +> Segment collects consent for both registered users and anonymous users. + +## Enforce consent +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. + +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. + +> warning "Segment recommends mapping all destinations to a category" +> Segment assumes any destinations without a mapping do not require user consent and will receive all events containing a consent object. + + + + +To learn more about configuring consent categories in your workspace, see the [Configure Consent Management documentation](/docs/privacy/configure-consent-management/). + +## Consent object + +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: + +```json +{ +"context": { + "consent": { + "consentPreferences": { + "Advertising": true, + "Analytics": false, + "Functional": true, + "DataSharing": false + } + } + } +} + +``` + + + +## Reconcile consent conflicts + +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). + +### Reconcile consent object and integrations object conflicts + +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. + +> success " " +> For more information about the Integrations object, please see [Filtering your Segment Data](/docs/guides/filtering-data/#filtering-with-the-integrations-object). + +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: + +| Consent Object | Integration Object | Result | +| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------ | +| Not provided

`"context": {`
`}` | Not provided or empty object | Data flows to all destinations | +| Empty consent object

`"context": {`
` "consent": {`
` }`
`}`
OR
`"context": {`
` "consent": {`
` "categoryPreference": {`
` }`
` }`
`}`| Not provided or empty object | Data does **NOT** flow to any mapped destinations - consent is considered to be `false` for all categories.

Data flows to all destinations **NOT** mapped to a consent category. | +| Not provided

`"context": {`
`}` | `{facebook: true,`
`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. | +| Empty consent object

`"context": {`
` "consent": {`
` }`
`}`
OR
`"context": {`
` "consent": {`
` "categoryPreference": {`
` }`
` }`
`}`| `{facebook: true,`
`amplitude: false}` | Data does **NOT** flow to any mapped destinations - consent is considered to be `false` for all categories.

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. | +| `{ad: true,`
`analytics: false}`

_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. | +| `{ad: true,`
`analytics: false}`

_ad = facebook, google-ads_
| 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).

No data flows to analytics destinations. | +| `{ad: true,`
`analytics: false}`

_ad = facebook, google-ads_
_analytics = amplitude_ | `{facebook: true,`
`amplitude: false}` | Data flows to all ad destinations, even though Google Ads is not present in the integrations object.

Data does **NOT** flow to analytics destinations. | +| `{ad: true,`
`analytics: false}`

_ad = facebook, google-ads_
_analytics = amplitude_ | `{facebook: false,`
`amplitude: false}` | Data only flows to Google Ads and not to Facebook, which is `false` in the integrations object.

Data does **NOT** flow to analytics destinations. | +| `{ad: true,`
`analytics: false}`

_ad = facebook, google-ads_
_analytics = facebook, amplitude_ | `{facebook: true,`
`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.

Data does **NOT** flow to analytics destinations. | +| `{ad: true,`
`analytics: true}`

_ad = facebook, google-ads_
_analytics = facebook, amplitude_ | `{facebook: true,`
`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. | +| `{ad: false,`
`analytics: true}`

_ad = facebook, google-ads_
_analytics = facebook, amplitude_ | `{facebook: true,`
`amplitude: false}` | When destinations are mapped to multiple categories, data only flows if consent is `true` for all categories.

In this example, data does **NOT** flow to any destination because of the interaction between the integrations and consent objects. | + +### Reconcile CMP and Segment consent category conflicts + +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. + +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. + +## Consent observability + + + +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__. \ No newline at end of file diff --git a/src/privacy/images/consent-overview.png b/src/privacy/images/consent-overview.png new file mode 100644 index 0000000000..1dfb7a344b Binary files /dev/null and b/src/privacy/images/consent-overview.png differ diff --git a/src/privacy/reconcile-consent.md b/src/privacy/reconcile-consent.md new file mode 100644 index 0000000000..a513ee0167 --- /dev/null +++ b/src/privacy/reconcile-consent.md @@ -0,0 +1,63 @@ +--- +title: Reconciling Consent Conflicts +hidden: true +--- + +Segment sends data only to destinations in categories consented to by the end user. When conflicts arise between the consent object and integrations object or your consent management tool, Segment reconciles consent according to the following tables. + + + +> info "Consent Management is in private beta" +> 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. + +## Reconcile consent category trait conflicts + +Segment detects when there are conflicting consent categories for a user and reconciles them according to the following table: + + + +## Reconcile a user's conflicting preferences + +If a user has conflicting preferences (for example, they consented yes for a category on mobile, but not on the web, or consented differently using two different emails) Segment routes data according to the following table: + +| Category | Consent on mobile | Consent on the web | +| -------- | ----------------- | ------------------ | + + + + +## Reconcile consent object and integrations object conflicts + +You can add the integrations object and the consent object to your Segment payloads to control how Segment routes data to your downstream destinations. + +> success " " +> For more information about the Integrations object, please see [Filtering your Segment Data](/docs/guides/filtering-data/#filtering-with-the-integrations-object). + +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: + + +| Consent Object | Integration Object | Result | +| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------ | +| Not provided or empty object | Not provided or empty object | Message delivered to all destinations | +| `context {consent{}}`
OR
`context {consent {categoryPreference{}}}` | Not provided or empty object | Data **NOT** delivered - consent is considered to be `false` for all categories | +| Not provided or empty object

`context{}` | `{facebook: true,`
`amplitude: false}` | Message and metadata delivered to Facebook | +| Empty consent object
`context {consent{}}`
OR
`context {``consent {``categoryPreference{}``}}` | `{facebook: true,`
`amplitude: false}` | Data **NOT** delivered - consent is considered to be `false` for all categories | +| `{ad: true,`
`analytics: false}`

_Segment has no category-to-destination mapping for ad and analytics_ | Provided, not provided, or empty object | Data **NOT** delivered | +| `{ad: true,`
`analytics: false}`

_ad = facebook, google ads_
| Not provided or empty object | Data delivered to destinations that map to consented purpose. In this case, data is delivered to all ad destinations (Facebook and Google Ads).

No data delivered to analytics destinations | +| `{ad: true,`
`analytics: false}`

_ad = facebook, google ads_
_analytics = amplitude_ | `{facebook: true,`
`amplitude: false}` | Data delivered to all ad destinations even though Google Ads is not present in the integrations object.
Metadata is sent from Facebook.

Data **NOT** delivered to analytics destinations. | +| `{ad: true,`
`analytics: false}`

_ad = facebook, google ads_
_analytics = amplitude_ | `{facebook: false,`
`amplitude: false}` | Data delivered only to Google Ads, not to Facebook. Data **NOT** delivered to analytics destinations. | +| `{ad: true,`
`analytics: true}`

_ad = facebook, google ads_
_analytics = facebook, amplitude_ | `{facebook: true,`
`amplitude: false}` | Data delivered to all ad destinations, including Facebook, because analytics is true.
Metadata is sent from Facebook.
No data is sent to Amplitude because it is `false` in the integrations object. | +| `{ad: false,`
`analytics: true}`

_ad = facebook, google ads_
_analytics = facebook, amplitude_ | `{facebook: true,`
`amplitude: false}` | Data **NOT** delivered to ad destinations. Data delivered to Facebook for analytics only and not to Amplitude. | + + +## Reconcile Consent Management tool and Segment tool conflicts + +If there is a mismatch in consent categories between your consent management tool and the Segment app, Segment reconciles the consent object according to the following table: + +| Consent Management Tool | Segment App | Result | +| ------------------------------------------------------ | ------------------------------------------------------------------------ | ------ | +| `{ad: true}` | There is no "ad" category | No data is shared to destinations that the customer may think of as "ad" destinations or may have been mapped in the consent management tool | +| `{person: true}` | There is no category `person`, but there is a `personalization` category | No data is shared to destinations the customer may consider `person` or the mapped `personalization` category | +| `{ad: true`,
`person: true`,
`analytics:true}` | The `ad`, `person`, `analytics`, and `functional` categories are mapped | Data will be shared with consenting categories of ad, person, and analytics.

No data will be shared with destinations mapped to `functional`, because this content is considered to be false. | +