segmentio · forstisabella · Sep 28, 2023 · Jul 31, 2023 · Sep 6, 2023 · Sep 7, 2023
@@ -1,13 +1,17 @@
 ---
 title: Configure Consent Management
 hidden: true
+related:
+  - "/privacy/consent-management/"
+  - "/privacy/consent-in-segment-connections/"
+  - "/privacy/consent-in-unify/"
 ---
 > 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. 
+After setting up your consent management platform (CMP), you can enforce the consent collected from your users by adding the [consent object](/docs/privacy/consent-in-segment-connections/#consent-object) to your events. 
 
-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.
+Once you've configured consent in the Segment app and updated your sources to contain consent preference in every event, your events are routed only to the categories your end users consented to share data with. Events without the consent preference will continue to flow to destinations without consent enforcement.
 
 ## Prerequisites
 
@@ -17,14 +21,14 @@ Once you've configured consent in the Segment app, your events are routed only t
 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”}. 
+- **Access to your web and mobile libraries**. After you set up consent categories in the Segment app, you need to integrate your CMP and your Segment sources using a wrapper or other solution. 
+
+<!-- TODO: fix above link to mobile consent repository-->
 
 ## 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. 
+> During private beta, AWS S3, 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**.
@@ -37,10 +41,29 @@ Before you can configure consent in Segment, take the following steps:
 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. 
+> Segment assumes all destinations without a mapping do not require user consent and will receive all events containing a consent object. If a destination is mapped to multiple categories, a user must consent to all categories for data to flow to the destination.
+
+## Step 2: Integrating your CMP with Segment
+
+Once you've created consent categories in the Segment app, you need to integrate your CMP with Segment. Segment recommends using a CMP wrapper, but you can use any solution provided it meets the following criteria:
+- Reads the end user consent preference from your CMP and includes the [consent object](/docs/privacy/consent-in-segment-connections/#consent-object) in every event
+- If using Unify and Engage, generates the [Segment Consent Preference](/docs/privacy/consent-in-unify/#segment-consent-preference-event) event every time a user provides or updates their consent preferences with their anonymousId and userId
+
+Segment provides a OneTrust wrapper for the following sources:
+- **Analytics.js**: Please follow the instructions from the README in the [@segment/analytics-consent-wrapper-onetrust repository](https://github.com/segmentio/analytics-next/tree/master/packages/consent/consent-wrapper-onetrust){:target="_blank"}.
+- **Kotlin**: Please follow the instructions from the README in the [@segment-integrations/analytics-kotlin-consent](https://github.com/segment-integrations/analytics-kotlin-consent/blob/main/README.md#getting-started){:target="_blank"} repository.
+<!--- will not be released alongside the other two libraries, commenting out for now. - **Swift**: Please follow the instructions from the README in the [@repository](){:target="_blank"}.-->
+
+If you'd like to integrate with any other CMP, Segment requires you to build your own wrapper or use any mechanism provided it meets the above requirements of data and event generation.
+
+> warning "Consent Management is not backwards compatible with Segment's legacy Android library"
+> If you are using Segment's legacy Android library, you will need to upgrade to [Kotlin](/docs/connections/sources/catalog/libraries/mobile/kotlin-android/migration/) before using Consent Management.
+
+<!--- 
+> warning "Consent Management is not backwards compatible with Segment's legacy iOS and Android libraries"
+> If you are using one of Segment's legacy mobile libraries (iOS or Android,) you will need to upgrade to [Swift](/docs/connections/sources/catalog/libraries/mobile/apple/migration/) or [Kotlin](/docs/connections/sources/catalog/libraries/mobile/kotlin-android/migration/) before using Consent Management. 
 
-## Step 2: Add the consent wrapper to Analytics.js
-Please follow the instructions from the README in the [@segment/analytics-consent-wrapper-onetrust repository](https://github.com/segmentio/analytics-next/tree/master/packages/consent/consent-wrapper-onetrust){:target="_blank"}.
+--->
 
 ## Edit consent categories
 

@@ -0,0 +1,81 @@
+---
+title: Consent in Segment Connections
+hidden: true
+related:
+  - "/privacy/consent-management/"
+  - "/privacy/configure-consent-management/"
+  - "/privacy/consent-in-unify/"
+---
+
+> 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.
+
+Segment Connections users can add the [consent object](#consent-object) to their sources to stamp events with the end user consent preferences captured by your consent management platform (CMP) and send them downstream to destinations in categories that an end user consented to share data with. Events without the consent object continue to flow to destinations without consent enforcement. 
+
+For more information about configuring consent categories, see the [Configure Consent Management](/docs/privacy/configure-consent-management/#step-1-create-consent-categories-in-the-segment-app) documentation.
+
+If your sources also contain the integrations object, Segment will look at the consent object first, and then take into account the integrations object according to the table in the [Reconcile consent object and integrations object](#reconcile-consent-object-and-integrations-object-conflicts) documentation.
+
+> info "Unify users must send an additional event to add consent preferences to Profiles"
+> If you use Unify, see the [Consent in Unify](/docs/privacy/consent-in-unify) documentation for more information about the Segment Consent Preference event, which Segment uses with the consent object to add consent preference to Profiles.
+
+## Consent object
+
+Segment requires every event from all of your sources to include the end user consent preferences, captured by your CMP 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": {
+    "categoryPreferences": {
+        "Advertising": true,
+        "Analytics": false,
+        "Functional": true,
+        "DataSharing": false
+      }
+    }
+  }
+}
+
+```
+
+<!-- Not currently in scope: The categories consented to by a user and a flag if a [consent conflict](#reconcile-consent-conflicts) exists are pulled from the consent object and are visible as traits on a user's profile in Unify. For more information about Consent in Unify, see the [Consent in Unify](/docs/privacy/consent-management-in-unify) docs.-->
+
+Events without the consent object will continue to flow to destinations without consent enforcement.
+
+## 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 or empty consent object <br><br> `"context": {` <br>`}` <br>OR<br> `"context": {`<br>`     "consent": {`<br>`     }`<br>`}` | Not provided or empty object | Data flows to all destinations. |
+| Empty categoryPreference object <br><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. |
+| 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.  |
+| 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.   |
+| `{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. |
+| `{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. |
+| `{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. |
+| `{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. |
+| `{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. |
+| `{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. |
+| `{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. |
+
+### 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.
+
+## Content 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*.
@@ -0,0 +1,49 @@
+---
+title: Consent in Unify
+hidden: true
+related:
+  - "/privacy/consent-management/"
+  - "/privacy/configure-consent-management/"
+  - "/privacy/consent-in-segment-connections/"
+---
+
+> info "Consent in Unify and Twilio Engage is currently unavailable."
+> However, Segment's OneTrust consent wrappers automatically generate the Segment Consent Preference Track event, which will be required for future integrations with Unify and Twilio Engage.
+
+Segment uses Profiles in [Unify](/docs/unify/) as the source of truth of an end user's consent preference when enforcing consent in Twilio Engage. To get consent preference on the Profile, Segment requires the use of the [Segment Consent Preference event](#segment-consent-preference-event) and [Identify](/docs/connections/spec/Identify) events to route events to Unify. The Segment Consent Preference and Identify event should include the [consent object](/docs/privacy/consent-in-segment-connections/#consent-object).
+
+## Segment Consent Preference event
+Every time an end user provides or updates their consent preferences, Segment requires you to generate a **Segment Consent Preference** event. If you are using [Segment's OneTrust consent wrappers](/docs/privacy/configure-consent-management/#step-2-integrating-your-cmp-with-segment), Segment automatically generates a Segment Consent Preference event. This event is required to add the end user’s consent preference on their Profile in Unify.
+
+For example, if an end user agreed to share their information for functional and advertising purposes but not for analytics or data sharing, the Segment Consent Preference [Track call](/docs/connections/spec/track/) demonstrating their new consent preferences would have the following format:
+
+``` json
+{
+  "anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895",
+  "type": "track",
+  "event": "Segment Consent Preference",
+  "userId": "u123",
+  "traits": {
+     "email": "peter@example.com",
+     "phone": "555-555-5555",
+  }
+  "timestamp": "2023-01-01T00:00:00.000Z",
+  "context": {
+    "consent": {
+      "categoryPreferences" : {
+        "Advertising": true,
+        "Analytics": false,
+        "Functional": true,
+        "DataSharing": false
+      }
+    }
+  }
+}
+```
+
+If you use Protocols, the Segment app automatically adds the Segment Consent Preference event to all your existing Tracking Plans and for every new Tracking Plan. Segment recommends you don’t edit or delete the default fields in the Segment Consent Preference events, but you can add new fields as needed.
+
+> info "Segment Consent Preference is a reserved event name"
+> Segment has standardized a series of reserved event names that have special semantic meaning and maps these events to tools that support them.
+>
+> See the [Semantic Events](/docs/connections/spec/semantic/) docs for more details.