Data Collection
This page describes our Segment's Consent Manager front-end implementation.

Introduction

Starting from @chordcommerce/gatsby-theme-autonomy v1.2.0+, our Gatsby Performance starter makes use of Segment's Consent Manager by default. This document describes the front-end configuration and technical implementation details.

What's Consent Manager?

Consent Manager is a Segment Analytics add-on with support to... consent management:
At its core, the Consent Manager empowers 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 Segment's 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 (tracking-preferences):
tracking-preferences cookie
Preferences are being 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).
The default implementation, in Chord's starter, assumes that you want to show the Consent Manager banner/popup to your users, prior tracking anything.
You will find below more technical implementation details. As well as, at the end of this document, a section that explains how to remove Consent Manager but keep automatic analytics tracking.

How does this work?

As mentioned above, Consent Manager controls the load process of our Segment Analytics plugin. In order to do so, we have configured the Segment plugin, present in our theme, to be loaded "manually" (by Consent Manager) in our starter.
You will find that manualLoad setting in your gatsby-config.js file, as follow:
plugins: [
{
resolve: '@chordcommerce/gatsby-theme-performance',
options: {
....
segmentConfig: {
prodKey: process.env.GATSBY_SEGMENT_PRODUCTION_WRITE_KEY,
devKey: process.env.GATSBY_SEGMENT_DEV_WRITE_KEY,
trackPage: true,
host: 'https://cdn.segment.com',
delayLoad: false,
delayLoadTime: 1000,
manualLoad: true
}
...
}
}
]
This configuration setting will be passed to our Segment plugin. Please read this to learn more details about it.
We will show you later on on this page how you can remove Consent Manager, should you choose not to use Consent Management.
Gatsby starter v2.3.0+ (Autonomy) ships with a new Consent Manager component. You will find it at: /src/components/Segment/ConsentManager/index.jsx.
That component is responsible for configuring and rendering a banner (or popup, depending on your level of customization) that will offer users an option to opt-in or out of tracking.
Please note that the Consent Manager banner is shown automatically for visitors from the EU. Please refer to the shouldRequireConsent method of the component to alter that behavior.
You can decide to show the banner for all visitors, regardless of their actual location, by configuring the GATSBY_SEGMENT_SHOULD_REQUIRE_CONSENT environment variable to true in your .env file.
You should then see the following:
Finally, we have integrated a way to manage your Consent Manager preferences from the starter's footer component. Users who have already allowed (or denied) tracking, can tweak their preferences from there:
Yes! Have a look at /src/components/Segment/ConsentManager/index.jsx . In there, you can tweak various properties (or see example below):
<ConsentManager
writeKey={writeKey}
shouldRequireConsent={shouldRequireConsent}
implyConsentOnInteraction={false}
bannerContent={bannerContent}
bannerSubContent="You can manage your preferences here!"
bannerActionsBlock={bannerActionsBlock}
bannerHideCloseButton={false}
bannerAsModal={false}
bannerTextColor="#FFFFFF"
bannerBackgroundColor="#38A169"
preferencesDialogTitle="Website Data Collection Preferences"
preferencesDialogContent={preferencesDialogContent}
cancelDialogTitle="Are you sure you want to cancel?"
cancelDialogContent={cancelDialogContent}
onError={onError}
/>
All those props (and more) can be found in Consent Manager's official documentation.

Where is the Consent Manager entry point in the application?

Consent Manager wraps the root page element of our Gatsby starter, as seen in gatsby-browser.js file:
import ConsentManagerWrapper from '~/components/Segment/ConsentManager'
/**
* Wraps the apps root element with Segment's Consent Manager.
*/
export const wrapPageElement = ({ element }) => {
return <ConsentManagerWrapper>{element}</ConsentManagerWrapper>
}
wrapPageElement.propTypes = {
element: propTypes.element.isRequired
}

Integrations

In order for Consent Manager to work, you must setup Segment integrations in your target Segment workspace.
You can verify that your integrations (Google Analytics, Amplitude, ...) are accessible for the Consent Manager component by visiting the URL below. The response should not return an empty array if you have properly configured them.
https://cdn.segment.com/v1/projects/add-your-segment-api-key-here/integrations
Alternatively, you can also verify that you have existing integrations by looking at your Source's dashboard in Segment:

Troubleshooting rendering issues

If you start customizing our ConsentManagerWrapper component, make sure that the {children} prop coming from the wrapRootElement is placed before the <ConsentManager /> node:
If you accidentally changed that order, you might run into this known Gatsby issue, where a blank page is rendered all over the site. This issue will only occur if you build and serve the site (as opposed to simply yarn dev).

Removing Consent Manager

Should you want to remove Consent Manager, and keep tracking your visitors automatically, please follow those steps:
  • Remove/uninstall the Consent Manager package "@segment/consent-manager" from your package.json
  • Remove the ConsentManagerWrapper , as shown above in gatsby-browser.js's wrapPageElement method.
  • Set manualLoad to false in the segmentConfig section of your gatsby-config.js. This will load our Segment plugin (contains in our theme) automatically, since Consent Manager has been removed. Tracking will kick in immediately on first page load.