@trustarc/trustarc-segment-wrapper

v1.1.2

Published

2 months ago

TrustArc wrapper for Segment

0High
0Medium
0Low

fbrito-trustarc

hyebahi-trustarc

trustarc segment consent analytics

TrustArc Segment Wrapper

Quick Start

Configure TrustArc + Segment

Requirements

Ensure that consent is enabled and that you have registered your integration-to-category mappings in Segment, which you can do through the Segment UI.

If you don't see a "Consent Management" option like the one below, please contact Segment's support or your Segment Solutions Engineer to have it enabled on your workspace.

Debugging hints: this library expects the TrustArc CCM script to be available in order to interact with TrustArc. This library derives the category IDs that are active for the current user from the window.truste object provided by TrustArc API.

For snippet users

Add TrustArc's snippet and integration to your page

<head>

  <!-- TrustArc Cookies Consent script start for CCM Advanced -->
  <script async="async" type="text/javascript" crossorigin="" src='//consent.trustarc.com/notice?domain=<instanceid>&c=teconsent&js=nj&noticeType=bb&gtm=1&'></script>

  <!-- TrustArc Cookies Consent script start for CCM Pro -->
  <script type="text/javascript" async="async" src="https://consent.trustarc.com/v2/notice/<instanceid>"></script>


  <!-- Add Segment's TrustArc Consent Wrapper -->
  <script src="https://consent.trustarc.com/get?name=trustarc-segment-wrapper-v1.1.js"></script>

  <!--
    Add / Modify Segment Analytics Snippet
    * Find and replace: analytics.load('<MY_WRITE_KEY>') -> TrustArcWrapper.withTrustArc(analytics).load('<MY_WRITE_KEY'>)
  -->
  <script>
    !function(){var analytics=window.analytics...
    ....
    TrustArcWrapper.withTrustArc(analytics).load('<MY_WRITE_KEY>') // replace analytics.load()
    analytics.page()
  </script>
</head>

⚠️ Reminder: you must modify `analytics.load('....')` from the original Segment snippet. See markup comment in example above.

For `npm` library users

Ensure that TrustArc Snippet is loaded.
Install both packages from your preferred package manager

# npm
npm install @trustarc/trustarc-segment-wrapper
npm install @segment/analytics-next

# yarn
yarn add @trustarc/trustarc-segment-wrapper
yarn add @segment/analytics-next   

# pnpm
pnpm add @trustarc/trustarc-segment-wrapper
pnpm add @segment/analytics-next

Initialize alongside analytics

import { withTrustArc } from '@trustarc/trustarc-segment-wrapper'
import { AnalyticsBrowser } from '@segment/analytics-next'

export const analytics = new AnalyticsBrowser()

withTrustArc(analytics).load({ writeKey: '<MY_WRITE_KEY'> })

Here is an example of how you can load the CCM script with useEffect

useEffect (() => {
    withTrustArc(analytics).load({ writeKey: '<MY_WRITE_KEY'>' })

    const taScript = document.createElement("script");
    taScript.src = "//consent.trustarc.com/notice?domain=<yourdomain.com>&c=teconsent&js=nj&noticeType=bb&gtm=1";
    document.head.appendChild(taScript);
   
    return () => {
      taScript.remove();
    }
  }, [])

Settings

Consent Models

opt-in - (strict, GDPR scenario) -- wait for explicit consent (i.e. alert box to be closed) before loading device mode destinations and initializing Segment. If consent is not given (no mapped categories are consented to), then Segment is not loaded. Opt-in experience is the mapped for EU or expressed values in the notice behavior. See instructions below for more information.
opt-out - Load segment immediately and all destinations, based on default categories. For device mode destinations, any analytics.js-originated events (e.g analytics.track) will be filtered based on consent.
default/other - opt-out

This wrapper uses the EU | US values from the notice_behavior cookie dropped for the CCM Advanced and EU | NA | AN | AF | AS | SA | OC for CCM Pro consent model according to the consent geolocation. Please refer to the TrustArc integration guide for a more comprehensive overview of the available options. The default behavior can also be customized using your own logic:

TrustArcWrapper.withTrustArc(analytics, { consentModel: () => 'opt-in' | 'opt-out' })
  .load({ writeKey: '<MY_WRITE_KEY>' })

If you are using implied | expressed to define the consent experience, you can inform that using the parameter consentModelBasedOnConsentExperience: true,.

TrustArcWrapper.withTrustArc(analytics, { consentModelBasedOnConsentExperience: true })
  .load({ writeKey: '<MY_WRITE_KEY>' })

Always Load Segment

Feature available in version 1.1 and later

If you are using Segment as a Required vendor, you can pass an additional parameter for Segment to load even on opt-in locations before there's any consent provided. This will allow Segment to load, while making sure that the visitor's consent choices are still propagated so that the destinations that are not mapped as required will not load.

IMPORTANT: Please always consult with your privacy team before enabling this option;

TrustArcWrapper.withTrustArc(analytics, { alwaysLoadSegment: true })
  .load({ writeKey: '<MY_WRITE_KEY>' })

Consider Unprovisioned Locations as Opt-Out

When you have locations that are not set in TrustArc's location settings (unprovisioned locations), by default the wrapper loads in opt-in mode. In such scenarios, it will remain in opt-in mode since unprovisioned locations will not provide a banner or option for users to make a consent decision.

If you want unprovisioned locations to load all destinations by default instead, you can use the considerUnprovisionedLocationsAsOptOut parameter to treat unprovisioned locations as opt-out.

TrustArcWrapper.withTrustArc(analytics, { considerUnprovisionedLocationsAsOptOut: true })
  .load({ writeKey: '<MY_WRITE_KEY>' })

Note: Please consult with your privacy team before enabling this option to ensure it aligns with your consent requirements.

Environments

Build Artifacts

The library is built in multiple formats to support different use cases:

| Format | Description | Path | |--------|-------------|------| | UMD | Universal Module Definition - works in browsers via <script> tag and module loaders | dist/index.js | | CommonJS | For Node.js and bundlers like webpack | dist/cjs/src/index.js | | ESM | ES Modules for modern bundlers and native browser imports | dist/esm/src/index.js |

Browser Support

This library supports all modern browsers. For supported browsers, see the Segment Analytics.js documentation.

Note: For legacy browser support, you may need to include polyfills for features like Promises, Object.assign, and Array methods depending on your target browsers.