Skip to content

Implement Segment TrustArc wrapper and consent-based third-party script loading#197

Closed
mlr wants to merge 4 commits intomainfrom
trustarc-consent
Closed

Implement Segment TrustArc wrapper and consent-based third-party script loading#197
mlr wants to merge 4 commits intomainfrom
trustarc-consent

Conversation

@mlr
Copy link
Copy Markdown
Contributor

@mlr mlr commented Oct 1, 2025 •
edited
Loading

Summary

Followup to #196 which switched from Ketch to IBM TrustArc. This PR implements the Segment TrustArc wrapper for consent-aware analytics tracking and adds consent checking to third-party scripts (Intercom).

Based on implementation from langflow-ai/website PR #71.

Changes

Segment Integration with TrustArc Wrapper

  • Load TrustArc Segment wrapper (trustarc-segment-wrapper-v1.1.js)
  • Initialize Segment via TrustArcWrapper.withTrustArc() to respect consent
  • Add IBM Segment Common Schema properties to all events
  • Implement data-attribute tracking (data-event, data-cta, etc.) following IBM standards

Consent-Based Script Loading

  • Intercom: Only loads with Functional consent (category 1)
  • Segment: Respects Analytics consent (category 3) via wrapper
  • Listen to TrustArc consent events (cm_data_subject_consent_changed, cm_consent_preferences_set)

Google Consent Mode v2

  • Set default consent to denied for all categories
  • Update consent state dynamically based on TrustArc categories
  • Map TrustArc categories to Google consent types (ad_storage, analytics_storage, etc.)

Script Loading Order Fix

  • Move IBM Analytics config and consent listeners to head-scripts.hbs
  • Ensures TrustArc config loads before Segment in the <head>
  • Critical for proper consent flow

Footer Update

  • Change "Manage Privacy Choices" to trigger TrustArc banner
  • Replace Ketch redirect with window.truste.eu.clickListener()
  • Switch from site.keys.ketchSmartTagUrl to site.keys.ibmAnalyticsEnabled

Files Modified

  • src/partials/head-scripts.hbs: Added IBM Analytics config, TrustArc wrapper initialization, Google Consent Mode setup
  • src/js/04-segment-analytics.js: Added data-attribute tracking with IBM Common Schema property mapping
  • src/partials/footer.hbs: Updated "Manage Privacy Choices" link to trigger TrustArc banner
  • src/partials/intercom.hbs: Added consent checking before loading Intercom widget
  • src/js/10-trustarc-consent.js: Deleted (content moved to head-scripts.hbs for proper load order)

Configuration Required

Update Antora playbook:

site:
  keys:
    segment: "YOUR_SEGMENT_WRITE_KEY"
    ibmAnalyticsEnabled: true
    intercom: "YOUR_INTERCOM_APP_ID" # optional

Update head-scripts.hbs IBM Segment Common Properties:

const SEGMENT_COMMON_PROPERTIES = {
  productTitle: '<ADD>',      // e.g., 'DataStax Documentation'
  productCode: '<ADD>',       // e.g., 'datastax-docs'
  productCodeType: '<ADD>',   // e.g., 'OCC'
  ut30: '<ADD>'               // IBM Unified Taxonomy code
};

How Consent Flow Works

  1. Page loads with IBM Analytics config in <head> (Google Consent Mode default: denied)
  2. IBM Common Stats script loads, displays TrustArc banner on first visit
  3. User grants consent via TrustArc banner
  4. TrustArc fires cm_consent_preferences_set event
  5. Consent listeners update Google Consent Mode and load consent-approved scripts
  6. Segment initializes via TrustArc wrapper, respecting Analytics consent
  7. Intercom loads if Functional consent granted
  8. All Segment events include IBM Common Schema properties

Event Tracking Examples

CTA Clicked Event

<button
  data-event="CTA Clicked"
  data-cta="Get Started"
  data-channel="webpage"
  data-text="Start Free Trial"
>
  Start Free Trial
</button>

Sends to Segment:

{
  CTA: "Get Started",
  channel: "webpage",
  text: "Start Free Trial",
  // Plus SEGMENT_COMMON_PROPERTIES
}

UI Interaction Event

<a
  data-event="UI Interaction"
  data-action="clicked"
  data-channel="webpage"
  data-element-id="nav-docs"
  data-namespace="header"
>
  Documentation
</a>

Sends to Segment:

{
  action: "clicked",
  channel: "webpage",
  elementId: "nav-docs",
  namespace: "header",
  // Plus SEGMENT_COMMON_PROPERTIES
}

TrustArc Consent Categories

Category Number Used For
Required 0 Essential site functionality (always allowed)
Functional 1 Enhanced features (Intercom)
Advertising 2 Ad personalization (Google Ads)
Analytics 3 Usage analytics (Segment, Google Analytics)

References

@mlr mlr force-pushed the trustarc-consent branch from fc1e50e to f84b9a1 Compare October 1, 2025 21:47
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Oct 1, 2025

UI bundle preview build failure! ❌

[21:47:59] Using gulpfile ~/work/docs-ui/docs-ui/gulpfile.js [21:47:59] Starting 'lint'... [21:48:00] /home/runner/work/docs-ui/docs-ui/src/js/04-segment-analytics.js 19:27 error Missing trailing comma comma-dangle 35:27 error Missing trailing comma comma-dangle ✖ 2 problems (2 errors, 0 warnings) 2 errors and 0 warnings potentially fixable with the --fix option. [21:48:00] 'lint' errored after 1.08 s [21:48:00] �[31mESLintError�[39m in plugin "�[36mgulp-eslint�[39m" Message: Failed with 2 errors

@plpesvc-ds

This comment has been minimized.

Sign in to view
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Oct 1, 2025 •
edited
Loading

UI bundle preview build successful! ✅
Deploying bundle preview.
Deploy successful! View preview

@mlr mlr changed the title trustarc consent Implement Segment TrustArc wrapper and consent-based third-party script loading Oct 1, 2025
@plpesvc-ds

This comment has been minimized.

Sign in to view
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Oct 1, 2025 •
edited
Loading

UI bundle preview build successful! ✅
Deploying bundle preview.
Deploy successful! View preview

@plpesvc-ds

This comment has been minimized.

Sign in to view
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Oct 1, 2025 •
edited
Loading

UI bundle preview build successful! ✅
Deploying bundle preview.
Deploy successful! View preview

@plpesvc-ds
Copy link
Copy Markdown

plpesvc-ds commented Oct 1, 2025 •
edited
Loading

Build successful! ✅
Deploying draft.
Deploy successful! View draft

@mlr mlr closed this Oct 9, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@mlr @plpesvc-ds