Add Usercentrics CMP (cookie consent + GDPR compliance)

Author: isstuev

configs/app/features/index.ts

@@ -50,4 +50,5 @@ export { default as validators } from './validators';
 export { default as verifiedTokens } from './verifiedTokens';
 export { default as web3Wallet } from './web3Wallet';
 export { default as xStarScore } from './xStarScore';
+export { default as usercentrics } from './usercentrics';
 export { default as zetachain } from './zetachain';

configs/app/features/usercentrics.ts

@@ -0,0 +1,32 @@
+import type { Feature } from './types';
+
+import app from '../app';
+import { getEnvValue, parseEnvJson } from '../utils';
+
+interface UsercentricsConfig {
+  readonly scriptUrl: string;
+  readonly rulesetId: string;
+}
+
+const title = 'Usercentrics CMP';
+
+const config: Feature<{ scriptUrl: string; rulesetId: string }> = (() => {
+  if (app.isPrivateMode) {
+    return Object.freeze({ title, isEnabled: false as const });
+  }
+
+  const rawConfig = parseEnvJson<UsercentricsConfig>(getEnvValue('NEXT_PUBLIC_USERCENTRICS_CONFIG') ?? '');
+
+  if (rawConfig?.scriptUrl && rawConfig?.rulesetId) {
+    return Object.freeze({
+      title,
+      isEnabled: true as const,
+      scriptUrl: rawConfig.scriptUrl,
+      rulesetId: rawConfig.rulesetId,
+    });
+  }
+
+  return Object.freeze({ title, isEnabled: false as const });
+})();
+
+export default config;

configs/envs/.env.eth

@@ -76,4 +76,5 @@ NEXT_PUBLIC_VIEWS_NFT_MARKETPLACES=[{'name':'OpenSea','collection_url':'https://
 NEXT_PUBLIC_VIEWS_TOKEN_SCAM_TOGGLE_ENABLED=true
 NEXT_PUBLIC_VISUALIZE_API_HOST=https://visualizer.services.blockscout.com
 NEXT_PUBLIC_XSTAR_SCORE_URL=https://docs.xname.app/the-solution-adaptive-proof-of-humanity-on-blockchain/xhs-scoring-algorithm?utm_source=blockscout&utm_medium=address
-NEXT_PUBLIC_API_KEYS_ALERT_MESSAGE='<strong>Chain-specific API keys are being deprecated.</strong> Please migrate to <a href="https://docs.blockscout.com/for-developers/api-keys/pro-api" target="_blank" rel="noopener noreferrer">Blockscout's PRO API</a> for new multichain access. Existing API keys will become invalid on 1st of Jan 2027'
+NEXT_PUBLIC_API_KEYS_ALERT_MESSAGE='<strong>Chain-specific API keys are being deprecated.</strong> Please migrate to <a href="https://docs.blockscout.com/for-developers/api-keys/pro-api" target="_blank" rel="noopener noreferrer">Blockscout's PRO API</a> for new multichain access. Existing API keys will become invalid on 1st of Jan 2027'
+NEXT_PUBLIC_USERCENTRICS_CONFIG={'scriptUrl': 'https://web.cmp.usercentrics.eu/ui/loader.js', 'rulesetId': 'bzr6TEix4Oas0i'}

cspell.jsonc

@@ -14,7 +14,8 @@
         "playwright/fixtures/rewards.ts",
         "public/static/capybara/index.js",
         "ui/showcases/utils.ts",
-        "ui/tx/TxExternalTxs.pw.tsx"
+        "ui/tx/TxExternalTxs.pw.tsx",
+        "configs/envs/**"
     ],
     "enableGlobDot": true,
     "ignoreRandomStrings": true,
@@ -250,6 +251,7 @@
         "unparse",
         "unstaked",
         "usehooks",
+        "usercentrics",
         "utia",
         "utka",
         "utko",

deploy/tools/envs-validator/schema.ts

@@ -146,6 +146,16 @@ const schema = yup
       }),
     NEXT_PUBLIC_FLASHBLOCKS_SOCKET_URL: yup.string().test(urlTest),
     NEXT_PUBLIC_HOT_CONTRACTS_ENABLED: yup.boolean(),
+    NEXT_PUBLIC_USERCENTRICS_CONFIG: yup
+      .mixed()
+      .test('shape', 'Invalid schema for NEXT_PUBLIC_USERCENTRICS_CONFIG, it should have scriptUrl and rulesetId', (data) => {
+        const isUndefined = data === undefined;
+        const valueSchema = yup.object().transform(replaceQuotes).json().shape({
+          scriptUrl: yup.string().test(urlTest).required(),
+          rulesetId: yup.string().required(),
+        });
+        return isUndefined || valueSchema.isValidSync(data);
+      }),
 
     // Misc
     NEXT_PUBLIC_USE_NEXT_JS_PROXY: yup.boolean(),

deploy/tools/envs-validator/test/.env.base

@@ -5,6 +5,7 @@ NEXT_PUBLIC_WALLET_CONNECT_FEATURED_WALLET_IDS=['xxx']
 NEXT_PUBLIC_RE_CAPTCHA_APP_SITE_KEY=xxx
 NEXT_PUBLIC_GOOGLE_ANALYTICS_PROPERTY_ID=UA-XXXXXX-X
 NEXT_PUBLIC_MIXPANEL_PROJECT_TOKEN=xxx
+NEXT_PUBLIC_USERCENTRICS_CONFIG='{"scriptUrl":"https://app.usercentrics.eu/browser-ui/latest/loader.js","rulesetId":"xxx"}'
 NEXT_PUBLIC_MIXPANEL_CONFIG_OVERRIDES='{"record_sessions_percent": 0.5,"record_heatmap_data": true}'
 NEXT_PUBLIC_GROWTH_BOOK_CLIENT_KEY=xxx
 NEXT_PUBLIC_AD_TEXT_PROVIDER=coinzilla

docs/ENVS.md

@@ -46,6 +46,7 @@ All json-like values should be single-quoted. If it contains a hash (`#`) or a d
   - [Export data to CSV file](#export-data-to-csv-file)
   - [Google analytics](#google-analytics)
   - [Mixpanel analytics](#mixpanel-analytics)
+  - [Usercentrics CMP](#usercentrics-cmp)
   - [GrowthBook feature flagging and A/B testing](#growthbook-feature-flagging-and-ab-testing)
   - [GraphQL API documentation](#graphql-api-documentation)
   - [API documentation](#api-documentation)
@@ -581,6 +582,14 @@ Ads are enabled by default on all self-hosted instances. If you would like to di
 
  
 
+### Usercentrics CMP
+
+| Variable | Type| Description | Compulsoriness  | Default value | Example value | Version |
+| --- | --- | --- | --- | --- | --- | --- |
+| NEXT_PUBLIC_USERCENTRICS_CONFIG | `object` | JSON config for [Usercentrics](https://usercentrics.com/) Consent Management Platform. When set, the UC script is injected and all analytics (Google Analytics, Mixpanel, Rollbar) are gated behind user consent. Disabled in private mode. | true | - | `{'scriptUrl':'https://your-cdn.com/uc.js','rulesetId':'<your-ruleset-id>'}` | v1.37.x+ |
+
+&nbsp;
+
 ### GrowthBook feature flagging and A/B testing
 
 | Variable | Type| Description | Compulsoriness  | Default value | Example value | Version |

global.d.ts

@@ -24,6 +24,9 @@ declare global {
     __envs: Record<string, string>;
     __multichainConfig?: MultichainConfig;
     __essentialDappsChains?: { chains: Array<EssentialDappsChainConfig> };
+    __ucCmp?: {
+      getConsentDetails(): Promise<{ consent?: { status?: string } }>;
+    };
   }
 
   namespace NodeJS {

lib/mixpanel/useInit.tsx

@@ -9,6 +9,7 @@ import config from 'configs/app';
 import * as cookies from 'lib/cookies';
 import dayjs from 'lib/date/dayjs';
 import getQueryParamString from 'lib/router/getQueryParamString';
+import useUsercentricsConsent from 'lib/usercentrics/useConsent';
 
 import * as userProfile from './userProfile';
 
@@ -17,14 +18,31 @@ const opSuperchainFeature = config.features.opSuperchain;
 export default function useMixpanelInit() {
   const [ isInitialized, setIsInitialized ] = React.useState(false);
   const router = useRouter();
+  const hasConsent = useUsercentricsConsent();
   const debugFlagQuery = React.useRef(getQueryParamString(router.query._mixpanel_debug));
+  const isInitializedRef = React.useRef(false);
 
   React.useEffect(() => {
     const feature = config.features.mixpanel;
     if (!feature.isEnabled) {
       return;
     }
 
+    if (!hasConsent) {
+      if (isInitializedRef.current) {
+        // Consent was withdrawn after Mixpanel was already running — stop all tracking
+        isInitializedRef.current = false;
+        setIsInitialized(false);
+        try {
+          mixpanel.opt_out_tracking();
+        } catch {
+          // opt_out_tracking can throw if called before Mixpanel's internal state is ready
+          mixpanel.disable();
+        }
+      }
+      return;
+    }
+
     const debugFlagCookie = cookies.get(cookies.NAMES.MIXPANEL_DEBUG);
 
     const mixpanelConfig: Partial<Config> = {
@@ -57,11 +75,12 @@ export default function useMixpanelInit() {
       'First Time Join': dayjs().toISOString(),
     });
 
+    isInitializedRef.current = true;
     setIsInitialized(true);
     if (debugFlagQuery.current && !debugFlagCookie) {
       cookies.set(cookies.NAMES.MIXPANEL_DEBUG, 'true');
     }
-  }, [ ]);
+  }, [ hasConsent ]);
 
   return isInitialized;
 }

lib/usercentrics/useConsent.ts

@@ -0,0 +1,39 @@
+import React from 'react';
+
+import config from 'configs/app';
+
+async function checkConsent(): Promise<boolean> {
+  if (!window.__ucCmp) {
+    return false;
+  }
+  const details = await window.__ucCmp.getConsentDetails();
+  return details.consent?.status === 'ALL_ACCEPTED';
+}
+
+export default function useUsercentricsConsent(): boolean {
+  const [ hasConsent, setHasConsent ] = React.useState<boolean>(!config.features.usercentrics.isEnabled);
+
+  React.useEffect(() => {
+    if (!config.features.usercentrics.isEnabled) {
+      return;
+    }
+
+    const updateConsent = async() => {
+      setHasConsent(await checkConsent());
+    };
+
+    // Get initial consent state
+    updateConsent();
+
+    // Re-check on every consent change and on CMP initialization
+    window.addEventListener('UC_CONSENT', updateConsent);
+    window.addEventListener('UC_UI_INITIALIZED', updateConsent);
+
+    return () => {
+      window.removeEventListener('UC_CONSENT', updateConsent);
+      window.removeEventListener('UC_UI_INITIALIZED', updateConsent);
+    };
+  }, []);
+
+  return hasConsent;
+}