consent-manager

> Drop-in consent management plugin for analytics.js

StoryBook

• 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

Segment Consent Manager

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.

Features

• 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:

{
  "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:

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.
]

Usage

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.

Standalone Script

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 <div>) 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:

#target-container {
  position: fixed;
  left: 0;
  right: 0;
  bottom: 0;
  z-index: 100;
}

<div id="target-container"></div>

Globals

The following global variables are also exposed:

• consentManager.version - 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.

ConsentManager

The ConsentManager 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

import React from 'react'
import { ConsentManager, openConsentManager } from '@segment/consent-manager'
import inEU from '@segment/in-eu'

export default function() {
  const bannerContent = (
    <span>
      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{' '}
      <a href="/docs/legal/website-data-collection-policy/">
        Website Data Collection Policy
      </a>
      .
    </span>
  )
  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 (
    <div>
      

      <button type="button">
        Website Data Collection Preferences
      </button>
    </div>
  )
}

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.

import React from 'react'
import Script from 'next/script'
import { ConsentManager, openConsentManager } from '@segment/consent-manager'

export default function Home() {
  const bannerContent = (
    <span>
      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{' '}
      <a href="/docs/legal/website-data-collection-policy/">
        Website Data Collection Policy
      </a>
      .
    </span>
  )
  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 (
    <div>
      </div></div>