Drop-in consent management plugin for analytics.js
npm install @segment/consent-manager> Drop-in consent management plugin for analytics.js
- Segment Consent Manager
- Features
- Usage
- Standalone Script
- Options
- Globals
- Callback Function
- ConsentManager
- Install
- Example
- Example in Next.js
- ConsentManager Props
- ConsentManagerBuilder
- Install
- Example
- ConsentManagerBuilder Props
- ConsentManagerBuilder Render Props
- Utility functions
- Setting Custom Anonymous ID
- Development
- Publishing New Version
- License
The Segment Consent Manager is an analytics.js add-on with support to consent management.
At its core, the Consent Manager empowers your visitors to control and customize their tracking preferences on a website. They can opt out entirely of being tracked, or selectively opt out of tools in which they don’t want their information stored.
It works by taking control of the analytics.js load process to only load destinations that the user has consented to and not loading analytics.js at all if the user has opted out of everything. The user's tracking preferences are saved to a cookie and sent as an identify trait (if they haven't opted out of everything) so that you can also access them on the server-side and from destinations (warehouse).
_Segment works to ensure the Consent Manager Tech Demo works with most of our product pipeline. We cannot ensure it works in your specific implementation or website. Please contact our Professional Services team for implementation support. Please see the License.txt included._
_Please note, Consent Manager is not currently compatible with Personas. Personas may send user data to destinations the user has explicitly opted out of for data collection._
- Give users the ability to opt-in or opt-out to tracking.
- Fine grained control of tools or categories used for tracking.
- 30s setup with a drop in script tag.
- Or fully customizable UI/UX through React components.
- EU traffic detection through [@segment/in-eu][ineu].
- Ability for visitors to reconsent and change preferences.
- Automatically updates to reflect the destinations you have enabled in Segment.
- 5.0.0: Consent Manager will add consent metadata to the context of all track calls:
Track call message payloads will be extended to include Consent metadata in the context object:
``js`
{
"context": {
"campaign": {},
"consent": {
"categoryPreferences": {
"Amplitude": true,
"Customer.io": true,
"Google Analytics": true,
"Webhooks": true
},
"defaultDestinationBehavior": "disable",
"destinationPreferences": {
"Amplitude": true,
"Customer.io": true,
"Google Analytics": true,
"Webhooks": true
}
}
},
"event": "Send Track Event Clicked",
"integrations": {
"All": false,
"Amplitude": true,
"HubSpot": false,
"Salesforce": false,
"Segment.io": true
}
}
Breaking Changes: Version 5.0.0 and above require that your analytics.js snippet include the method addSourceMiddleware in the analytics.methods array:
`js`
analytics.methods = [
'trackSubmit',
'trackClick',
'trackLink',
'trackForm',
'pageview',
'identify',
'reset',
'group',
'track',
'ready',
'alias',
'debug',
'page',
'once',
'off',
'on',
'addSourceMiddleware' // This method is necessary for Consent Manager to forward consent metadata.
]
The Segment Consent Manager can be used in several ways, depending on how custom you want your visitor's experience to be.
To get started, make sure you're using the latest version of the [analytics.js snippet][] (4.1.0 or above) and remove the analytics.load("YOUR_WRITE_KEY"); call (so the consent manager can manage the loading process). Then continue onto one of the implementation methods below.
The standalone script is a prebuilt bundle that uses the [ConsentManager][] React component with [Preact][] (a lightweight React alternative). It's best for if you want to get up and running quickly or you don't have a preexisting React setup.
Include the consent manager script tag after your analytic.js snippet and add your own custom copy. The standalone script can be configured in one of two ways, via data attributes for simple usage or via a global callback function for advanced usage. Both methods allow the consent manager script to be loaded async.
#### Options
All of the [ConsentManager][] options are supported with the addition of these options:
##### container
Type: string
[CSS selector][] to the DOM element that will host the consent banner. It should be an empty DOM element (usually a
) because the consent manager will replace any existing DOM elements inside it. The element must also exist on the page before the script is executed.You can also control the positioning of the consent banner by applying styles to the container element (optional). E.g:
`css
#target-container {
position: fixed;
left: 0;
right: 0;
bottom: 0;
z-index: 100;
}
`html
`#### Globals
The following global variables are also exposed:
-
- Version of the consent manager.
- consentManager.openConsentManager() - Opens the consent manager preferences dialog.
- consentManager.doNotTrack() - Utility function that returns the user's Do Not Track preference (normalises the cross browser API differences). Returns true, false or null (no preference specified).
- consentManager.inEU() - The [@segment/in-eu][ineu] inEU() function.
- consentManager.preferences - Returns an instance of PreferencesManager with the following helper functions:
- loadPreferences - returns the cookie value for consent preferences
- savePreferences - allows for managing the consent cookie programatically (useful if you want to re-hydrate consent from your own database or prefill consent options)
- onPreferencesSaved(callback) - allows for subscribing to changes in preferences.#### Callback Function
All the options are supported. The callback function also receives these exports:
-
React - Reference to the [Preact][] library (the API is React compatible). Useful for if you need to use virtual DOM in your content.
- version - Version of the consent manager.
- openConsentManager() - Opens the consent manager preferences dialog.
- doNotTrack() - Utility function that returns the user's Do Not Track preference (normalises the cross browser API differences). Returns true, false or null (no preference specified).
- inEU() - The [@segment/in-eu][ineu] inEU() function.
- consentManager.preferences - Returns an instance of PreferencesManager with the following helper functions:
- loadPreferences - returns the cookie value for consent preferences
- savePreferences - allows for managing the consent cookie programatically (useful if you want to re-hydrate consent from your own database or prefill consent options)
- onPreferencesSaved(callback) - allows for subscribing to changes in preferences.`html
defer
>
`$3
The
React component is a prebuilt consent manager UI (it's the one we use on https://segment.com) that uses the [ConsentManagerBuilder][] component under the hood. To use it, just mount the component where you want the consent banner to appear and pass in your own custom copy._Note: Consent Manager is React-based so is not currently compatible with other frameworks such as Vue.js or Angular. In case you want to use it in another framework that is not React, you should use the Standalone implementation._
#### Install
Using npm:
`
npm install @segment/consent-manager
Using yarn:
yarn add @segment/consent-manager
#### Example
javascript
import React from 'react'
import { ConsentManager, openConsentManager } from '@segment/consent-manager'
import inEU from '@segment/in-eu'export default function() {
const bannerContent = (
We use cookies (and other similar technologies) to collect data to improve your experience on
our site. By using our website, you’re agreeing to the collection of data as described in our{' '}
Website Data Collection Policy
.
)
const bannerSubContent = 'You can change your preferences at any time.'
const preferencesDialogTitle = 'Website Data Collection Preferences'
const preferencesDialogContent =
'We use data collected by cookies and JavaScript libraries to improve your browsing experience, analyze site traffic, deliver personalized advertisements, and increase the overall performance of our site.'
const cancelDialogTitle = 'Are you sure you want to cancel?'
const cancelDialogContent =
'Your preferences have not been saved. By continuing to use our website, you՚re agreeing to our Website Data Collection Policy.'
return (
"
shouldRequireConsent={inEU}
bannerContent={bannerContent}
bannerSubContent={bannerSubContent}
preferencesDialogTitle={preferencesDialogTitle}
preferencesDialogContent={preferencesDialogContent}
cancelDialogTitle={cancelDialogTitle}
cancelDialogContent={cancelDialogContent}
/>
)
}
`#### Example in Next.js
In Next.js we do not have an html file where to inject the script. Here we will use the Script component to inject the snippet provided by Segment.
javascript
import React from 'react'
import Script from 'next/script'
import { ConsentManager, openConsentManager } from '@segment/consent-manager'export default function Home() {
const bannerContent = (
We use cookies (and other similar technologies) to collect data to improve your experience on
our site. By using our website, you’re agreeing to the collection of data as described in our{' '}
Website Data Collection Policy
.
)
const bannerSubContent = 'You can change your preferences at any time.'
const preferencesDialogTitle = 'Website Data Collection Preferences'
const preferencesDialogContent =
'We use data collected by cookies and JavaScript libraries to improve your browsing experience, analyze site traffic, deliver personalized advertisements, and increase the overall performance of our site.'
const cancelDialogTitle = 'Are you sure you want to cancel?'
const cancelDialogContent =
'Your preferences have not been saved. By continuing to use our website, you՚re agreeing to our Website Data Collection Policy.'
return (
dangerouslySetInnerHTML={{
__html: !function(){var analytics=window.analytics=window.analytics||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Segment snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware"];analytics.factory=function(e){return function(){var t=Array.prototype.slice.call(arguments);t.unshift(e);analytics.push(t);return analytics}};for(var e=0;e
}}();
}}
/>
bannerContent={bannerContent}
bannerSubContent={bannerSubContent}
preferencesDialogTitle={preferencesDialogTitle}
preferencesDialogContent={preferencesDialogContent}
cancelDialogTitle={cancelDialogTitle}
cancelDialogContent={cancelDialogContent}
bannerActionsBlock={true}
/>
)
}
`#### ConsentManager Props
This section lists the configurable props you can change when
loading the out of the box Consent Manager. In this demo, these are all the props you can pass into the returned preferences object.
- writeKey
- otherWriteKeys
- shouldRequireConsent
- initialPreferences
- closeBehavior
- implyConsentOnInteraction
- defaultDestinationBehavior
- cookieDomain
- bannerContent
- bannerSubContent
- bannerTextColor
- bannerBackgroundColor
- bannerActionsBlock
- bannerHideCloseButton
- bannerAsModal
- preferencesDialogTitle
- preferencesDialogContent
- cancelDialogTitle
- cancelDialogContent
- customCategories
- preferencesDialogTemplate
##### writeKey
Type:
Default: noneThe write key analytics.js should be loaded with.
You can find more information here.
https://segment.com/docs/connections/find-writekey
##### otherWriteKeys
Type:
Default: Write keys for other sources so you can include destinations they use in the Consent Manager tool list. This only displays destinations that are not connected to the primary writeKey.
The user’s consent preferences for these tools are not sent to these additional sources, but they are added to the
call the Consent Manager sends to Segment. The user’s preferences can then be added to a raw data destination (like a data warehouse) or to a user profile in Personas.##### shouldRequireConsent
Type:
function
Default: Callback function that determines if consent is required before tracking begins. Set to
to show the consent banner, otherwise return false to not show consent banner and start tracking immediately.The function can return a
Promise that resolves to a boolean.##### initialPreferences
Type: object
Default: {}
Object that opts into users into tracking for the different tracking categories. For example
{‘Functional’:true}##### closeBehavior
Type:
or function
Default: This option sets the default behavior for the x (close) button on the Consent Manager banner. Available options:
- “dismiss” - dismisses the banner, but doesn't save or change any preferences. Analytics.js won’t load until consent is given.
- “accept”- assume consent across every category.
- ”deny” - denies consent across every category.
can also be customized - i.e. don't load some categories, but load everything else. For example, if you wanted to load everything _except_ advertising, you could pass the following as closeBehavior:`js
closeBehavior={
(categories) => ({
...categories,
advertising: false
})
}
`##### implyConsentOnInteraction
_Breaking Change_ (versions < 3.0.0 will default this option
)Type:
boolean
Default: (as of 3.0.0)Determines whether or not consent should be implied if the user interacts with the website by clicking anywhere outside the Consent Manager banner.
##### defaultDestinationBehavior
Type:
string
Default: Determines what the Consent Manager does if the user has already made consent selections and it detects new destination tools. (This is determined by checking if the user already has a cookie set on their browser.)
This is relevant when you've added a connected a new destination to any of the sources managed by Consent Manager.
Options:
-
(default) - When you add new destinations, they are set to “disabled” unless a user updates their consent selections by default.
- enable - When you add new destinations, they are set to “enabled” unless a user updates their consent selections.
- imply - When you add new destinations, they are enabled or disabled based on the category to which they belong and the user's previous consent to that category.
For example, if a user already consented to the marketingAndAnalytics category, and you add a new destination which is in the Analytics category, that destination will be enabled until the user updates their consent selections.
- ask - When you add new destinations, the Consent Manager automatically opens the preferences dialog on initialization, and asks the user for their consent again.##### cookieDomain
Type:
string
Default: the top most domain and all sub domainsThe domain the
cookie should be scoped to.##### bannerContent
Type:
PropTypes.nodeThe content of the consent banner.
##### bannerSubContent
Type:
The call to action under the primary text in the Consent Manager banner.
##### bannerActionsBlock
Type:
The flag or function to render the actions block. If
value is passed - will render the default buttons block with Accept all and Deny all (required for the GDPR compliance). if the function is passed - will render the passed function into a actions block placeholder.Function props:
-
acceptAll: () => void - accept all cookies and close the banner
- denyAll: () => void - deny all cookies and close the banner
- changePreferences: () => void - open the dialog##### bannerTextColor
Type:
string
Default: The color of the consent banner text.
##### bannerBackgroundColor
Type:
Default: The color of the consent banner background.
##### bannerHideCloseButton
Type:
Default: Hide the close button of the consent banner.
##### bannerAsModal
Type:
Default: Show the consent banner as a modal, blocking the interaction while it is not accepted/rejected.
##### preferencesDialogTitle
Type:
Default: The title of the preferences dialog.
##### preferencesDialogContent
Type:
The top descriptive content of the preferences dialog.
##### cancelDialogTitle
Type:
Default: The title of the cancel dialog.
##### cancelDialogContent
Type:
The text displayed in the cancel dialog box.
##### customCategories
Type:
Default: An object that represents custom consent categories, and which tools are included in these categories. For example, for CCPA compliance, you could create a custom “Do Not Sell” category and list relevant destinations to it.
_Note: Calling the
object will overwrite the prebuilt categories (Analytics, Functional, Targeting and Advertising) provided by Consent Manager. Those categories will need to be redeclared inside customCategories. You can find examples here and here._`javascript
const customCategories = {
'New Category': {
purpose: 'A new consent category to capture more granular consent groupings',
integrations: ['Google Adwords (Classic)', 'Amplitude', 'Slack']
}
}
`The values for
should be an integration's creationName (integration.creationName). You can find examples of that by going to https://cdn.segment.com/v1/projects/##### preferencesDialogTemplate
Type:
Default:javascript
{
headings: {
allowValue: 'Allow',
categoryValue: 'Category',
purposeValue: 'Purpose',
toolsValue: 'Tools'
},
checkboxes: {
noValue: 'No',
yesValue: 'Yes'
},
actionButtons: {
cancelValue: 'Cancel',
saveValue: 'Save'
},
cancelDialogButtons: {
cancelValue: 'Yes, Cancel',
backValue: 'Go Back'
},
categories: [
{
key: 'functional',
name: 'Functional',
description:
'To monitor the performance of our site and to enhance your browsing experience.',
example: 'For example, these tools enable you to communicate with us via live chat.'
},
{
key: 'marketing',
name: 'Marketing and Analytics',
description:
'To understand user behavior in order to provide you with a more relevant browsing experience or personalize the content on our site.',
example:
'For example, we collect information about which pages you visit to help us present more relevant information.'
},
{
key: 'advertising',
name: 'Advertising',
description:
'To personalize and measure the effectiveness of advertising on our site and other websites.',
example:
'For example, we may serve you a personalized ad based on the pages you visit on our site.'
},
{
key: 'essential',
name: 'Essential',
description: 'We use browser cookies that are necessary for the site to work as intended.',
example:
'For example, we store your website data collection preferences so we can honor them if you return to our site. You can disable these cookies in your browser settings but if you do the site may not work as intended.'
}
]
}
`An object that represents the text fields of the preferences dialog and allows customizing them.
We recommend copying the default object and changing the fields as necessary.
_Note: All fields are optional. If they are not included in the template (object) the default fields will be used._
_Note 2: For categories, you need to provide the key in order to map all the values properly._
$3
The
React component is a low level render props component for building your own consent manager UI. It abstracts away all the logic for fetching destinations, checking/saving consent and loading analytics.js._Note: ConsentManagerBuilder is React-based so is not currently compatible with other frameworks such as Vue.js or Angular. In case you want to use it in another framework that is not React, you should use the Standalone implementation._
#### Install
Using npm:
`
npm install @segment/consent-manager
Using yarn:
yarn add @segment/consent-manager
#### Example
For a more detailed/advanced example, checkout the [ConsentManager implementation][].
javascript
import React from 'react'
import { ConsentManagerBuilder } from '@segment/consent-manager'export default function() {
return (
{({ destinations, preferences, setPreferences, saveConsent }) => (
Tracking tools
{destinations.map(destination => (
))}
)}
)
}
`#### ConsentManagerBuilder Props
- children
- writeKey
- otherWriteKeys
- shouldRequireConsent
- initialPreferences
- defaultDestinationBehavior
- mapCustomPreferences
- cookieDomain
- shouldReload
- devMode
##### children
Type:
The render props function that returns your UI.
##### writeKey
Type:
The write key analytics.js should be loaded with.
##### otherWriteKeys
Type:
Default: Other write keys that you want to load destination information for. This is useful for including your server-side destinations in the consent manager, so that you can easily apply the user's tracking preferences to your server-side analytics too. _No data will be sent to these write keys._
##### shouldRequireConsent
Type:
Default: Callback function that determines if consent is required before tracking can begin. Return
to show the consent banner and wait for consent (if no consent has been given yet). Return false to not show the consent banner and start tracking immediately (unless the user has opted out). The function can return a Promise that resolves to a boolean.##### initialPreferences
Type:
object
Default: The initial value of the preferences. By default it should be an object map of
. If you're using [mapCustomPreferences][] it should be an object map of your custom preferences' default values.##### defaultDestinationBehavior
Type:
string
Default: Determines what the Consent Manager does if the user has already made consent selections and it detects new destination tools. (This is determined by checking if the user already has a cookie set on their browser.)
This is relevant when you've added a connected a new destination to any of the sources managed by Consent Manager.
Options:
-
(default) - When you add new destinations, they are set to “disabled” unless a user updates their consent selections by default.
- enable - When you add new destinations, they are set to “enabled” unless a user updates their consent selections.
- imply - When you add new destinations, they are enabled or disabled based on the category to which they belong and the user's previous consent to that category.
For example, if a user already consented to the marketingAndAnalytics category, and you add a new destination which is in the Analytics category, that destination will be enabled until the user updates their consent selections.
- ask - When you add new destinations, the Consent Manager automatically opens the preferences dialog on initialization, and asks the user for their consent again.This setting also also affects Replays to new destinations. Only
disable and enable apply to these replays. If you set defaultDestinationBehavior to imply, Segment interprets this as enable during a replay.##### mapCustomPreferences
Type:
function
Default: Callback function allows you to use a custom preferences format (e.g: categories) instead of the default destination based one. The function gets called during the consent saving process and gets passed
. The function should return {destinationPreferences, customPreferences} where destinationPreferences is your custom preferences mapped to the destinations format ({destiantionId: true|false}) and customPreferences is your custom preferences if you changed them in the callback (optional).##### cookieDomain
Type:
string
Default: the [top most domain][top-domain] and all sub domainsThe domain the
cookie should be scoped to.##### shouldReload
Type:
boolean
Default: Reload the page if the trackers have already been initialized so that the user's new preferences can take effect.
##### devMode
Type:
Default: Disable the analitics.load to make local testing.
#### ConsentManagerBuilder Render Props
- destinations
- newDestinations
- preferences
- destinationPreferences
- havePreferencesChanged
- isConsentRequired
- workspaceAddedNewDestinations
- setPreferences
- resetPreferences
- saveConsent
- onError
##### destinations
Type: